내부정기권 날짜별 사용량 조회 API 가이드

개요

내부정기권의 동/호수별 날짜별 사용량을 조회하는 API입니다.

개요

내부정기권의 동/호수별 날짜별 사용량을 조회하는 API입니다.
구매 가능한 모든 시작일에 대해 해당 기간과 겹치는 차량 수를 반환합니다.

서비스 메서드

`InternalTicketUsageService.getUsageByDateRange()`

위치: CommonModule/src/main/java/com/akc/b2c/common/service/InternalTicketUsageService.java

// 신규 구매용 (7일치)
List<InternalTicketUsageByDateDto> getUsageByDateRange(
    String plotId,        // 주차장 ID
    String gdsId,         // 정기권 ID
    String buildingDong,  // 건물 동
    String unitNumber     // 호수
)

응답 DTO

`InternalTicketUsageByDateDto`

위치: CommonModule/src/main/java/com/akc/b2c/common/dto/InternalTicketUsageByDateDto.java

필드	타입	설명
`startDate`	String	시작일 (YYYYMMDD)
`endDate`	String	종료일 (YYYYMMDD)
`usedCount`	Long	해당 기간과 겹치는 사용 차량 수

사용 예시

1. 서비스 주입

import com.akc.b2c.common.service.InternalTicketUsageService;
import com.akc.b2c.common.dto.InternalTicketUsageByDateDto;

@Service
@RequiredArgsConstructor
public class YourService {
    
    private final InternalTicketUsageService internalTicketUsageService;
    
    public void yourMethod() {
        
        List<InternalTicketUsageByDateDto> usageList = 
            internalTicketUsageService.getUsageByDateRange(
                "02343",   // 주차장 ID
                "RR00010346",    // 정기권 ID
                "101",        // 동
                "1001"        // 호수
            );
    }
}

응답 예시

조건

오늘: 2026년 1월 27일
정기권 타입: RTM_0002 (한달 정기권)
기존 주문: 1/1 ~ 1/31, 차량 2대 등록

응답 (신규 구매, 7일치)

[
  { "startDate": "20260127", "endDate": "20260226", "usedCount": 2 },
  { "startDate": "20260128", "endDate": "20260227", "usedCount": 2 },
  { "startDate": "20260129", "endDate": "20260228", "usedCount": 2 },
  { "startDate": "20260130", "endDate": "20260301", "usedCount": 2 },
  { "startDate": "20260131", "endDate": "20260302", "usedCount": 2 },
  { "startDate": "20260201", "endDate": "20260303", "usedCount": 0 },
  { "startDate": "20260202", "endDate": "20260304", "usedCount": 0 }
]

해석

시작일	기존 주문(1/1~1/31)과 겹침?	usedCount
1/27	✅ 겹침 (1/31 >= 1/27)	2
1/31	✅ 겹침 (1/31 >= 1/31)	2
2/1	❌ 안겹침 (1/31 < 2/1)	0

응답 예시 (RTM_0001 월 고정 정기권)

조건

오늘: 2026년 1월 27일
정기권 타입: RTM_0001 (월 고정 정기권)
기존 주문: 1/1 ~ 1/31, 차량 2대 등록

응답 (신규 구매, 오늘 포함 7일)

구매 가능 범위: 1/27 ~ 2/2 → 1월, 2월 해당

[
  { "startDate": "20260101", "endDate": "20260131", "usedCount": 2 },
  { "startDate": "20260201", "endDate": "20260228", "usedCount": 0 }
]

해석

월	시작일	종료일	기존 주문(1/1~1/31)과 겹침?	usedCount
1월	1/1	1/31	✅ 겹침	2
2월	2/1	2/28	❌ 안겹침	0

포인트: RTM_0001은 월별로 1개씩만 반환됩니다. 시작일은 항상 해당 월의 1일입니다.

조건 2: 오늘이 2월 3일인 경우

오늘: 2026년 2월 3일
구매 가능 범위: 2/3 ~ 2/9 → 2월만 해당

응답

[
  { "startDate": "20260201", "endDate": "20260228", "usedCount": 0 }
]

포인트: 범위가 2월 내에서만 유효하므로 2월 1건만 반환됩니다.

정기권 타입별 종료일 계산

rglTkMthdId	이름	종료일 계산
`RTM_0001`	월 고정 정기권	시작일이 속한 월의 마지막 날
`RTM_0002`	한달 정기권	시작일 + 1달 - 1일

예시

정기권 타입	시작일	종료일
RTM_0001	2026-01-15	2026-01-31
RTM_0001	2026-02-10	2026-02-28
RTM_0002	2026-01-15	2026-02-14
RTM_0002	2026-02-10	2026-03-09

조회 일수

isExtension	용도	조회 일수
`false` (기본값)	신규 구매	오늘 포함 7일 (7개)
`true`	연장 구매	오늘 포함 14일 (14개)

기존 REST API

PaymentService에 이미 REST API가 구현되어 있습니다:

GET /api/payments/internal-ticket/usage/by-date
    ?plotId=xxx
    &gdsId=xxx
    &buildingDong=xxx
    &unitNumber=xxx
    &isExtension=false

유효한 주문 조건 (참고)

사용량 집계 시 아래 조건을 만족하는 주문만 카운트합니다:

결제 완료: payment_status = 'PAID'
전액 환불 아님: refund_status != 'COMPLETED'
기간 겹침: start_date <= 구매종료일 AND end_date >= 구매시작일
활성 차량만: order_cars.status IN ('REGISTERED', 'REFUND_REQUESTED', 'REFUND_REJECTED')

주의사항

parkingCapacity 필요 없음: 이 API는 순수하게 사용량만 반환합니다. 구매 가능 여부 판단이 필요하면 getAvailabilityByDateRange() 메서드를 사용하세요.
내부정기권 전용: is_internal = true인 주문만 집계합니다.
동/호수 필수: building_dong, unit_number가 NULL인 주문은 집계되지 않습니다.

파일	설명
`CommonModule/.../InternalTicketUsageService.java`	서비스 로직
`CommonModule/.../InternalTicketUsageByDateDto.java`	응답 DTO
`CommonModule/.../InternalTicketUsageRepository.java`	쿼리 Repository
`PaymentService/.../InternalTicketController.java`	REST API 컨트롤러

문의

구현 관련 문의사항은 Payment 개발팀에 연락해주세요.

내부정기권 사용량 집계 (v2)

프로젝트 기술 문서 모음