관리자 주문 조회 API 명세서

🎯 이 문서의 목적: 관리자가 회원별/티켓별 주문 내역을 조회할 수 있는 API를 제공합니다.
각 API 섹션 상단의 빠른 시작 부분에서 바로 테스트할 수 있는 예시를 확인하세요.

📑 목차

회원별 구매내역 조회 API - 특정 회원의 모든 주문 조회
티켓별 구매내역 조회 API - 특정 티켓의 모든 구매 내역 조회
공통 응답 구조 (OrderInfo DTO) - 주문 정보 상세 구조
Enum 상태값 정의 - 주문/결제/환불 상태값
참고 사항 - 날짜 처리, 성능 최적화 등

1. 회원별 구매내역 조회 API

한 줄 요약: 관리자가 특정 회원의 전체 주문 내역을 조회 (숨김 처리된 주문 포함)

🚀 빠른 시작

요청 예시

GET /api/payments/orders/admin/member-purchases?memberId=12345&createdAtFrom=20260101&createdAtTo=20261231&scope=ONGOING&page=0&size=20
Authorization: Bearer {관리자_토큰}

응답 예시

{
  "success": true,
  "errorCode": null,
  "message": null,
  "timestamp": "2026-04-01T10:30:45",
  "data": {
    "content": [
      {
        "orderId": "ORD20260401123456",
        "parkingLotId": "PLOT001",
        "parkingTicketId": "RT00012345",
        "type": "REGULAR",
        "orderStatus": "AVAILABLE",
        "paymentStatus": "PAID",
        "finalPrice": 95000,
        "paymentAmt": 94500,
        "startDateAt": "2026-04-01T00:00:00",
        "endDateAt": "2026-05-01T23:59:59",
        "userInfo": {
          "userId": "user123",
          "name": "홍길동",
          "email": "hong@example.com",
          "phoneNumber": "010-1234-5678"
        },
        "parkingLotInfo": {
          "plotId": "PLOT001",
          "plotName": "강남 타워 주차장"
        }
      }
    ],
    "pageNumber": 0,
    "pageSize": 20,
    "totalElements": 100,
    "totalPages": 5,
    "last": false
  }
}

💡 바로 테스트하기: memberId와 날짜 범위만 수정하여 즉시 사용 가능합니다.

📋 상세 정보

기본 정보

HTTP 메서드: GET
URL: /api/payments/orders/admin/member-purchases
인증: Bearer Token 필요 (관리자 권한)
특징: isHidden 필터가 적용되지 않아, 숨김 처리된 주문도 모두 조회됩니다.

요청 파라미터

필수 파라미터:

파라미터	타입	설명
memberId	Long	조회할 회원의 ID
createdAtFrom	String	구매일 시작 날짜 (KST 기준, 형식: yyyyMMdd)
createdAtTo	String	구매일 종료 날짜 (KST 기준, 형식: yyyyMMdd)

선택 파라미터:

파라미터	타입	기본값	설명	가능한 값
scope	String	ALL	주문 범위 필터	`ALL` (모든 주문) / `ONGOING` (진행 중인 주문 - 티켓이 만료되지 않았고, 전액 환불되지 않은 주문) / `COMPLETED` (완료된 주문 - 티켓이 만료되었거나, 전액 환불된 주문)
type	String	-	주문 유형 필터	`REGULAR` (일반 정기권) / `SUBSCRIPTION` (구독권) / `PARKING` (주차권)
parkingLotId	String	-	주차장 ID 필터	-
page	Integer	0	페이지 번호 (0부터 시작)	-
size	Integer	20	페이지 크기	-

응답 구조

응답의 data.content 배열에는 OrderInfo 객체가 포함됩니다. (상세 구조는 공통 응답 구조 참조)

{
  "success": true,
  "data": {
    "content": [/* OrderInfo 배열 */],
    "pageNumber": 0,
    "pageSize": 20,
    "totalElements": 100,
    "totalPages": 5,
    "last": false
  }
}

📚 추가 사용 예시

예시 1: 전체 구매내역 조회

GET /api/payments/orders/admin/member-purchases?memberId=12345&createdAtFrom=20260101&createdAtTo=20261231&page=0&size=20

→ 회원 ID 12345의 2026년 전체 구매내역을 20개씩 조회

예시 2: 진행 중인 주문만 조회

GET /api/payments/orders/admin/member-purchases?memberId=12345&createdAtFrom=20260101&createdAtTo=20261231&scope=ONGOING

→ 아직 만료되지 않았고 전액 환불되지 않은 주문만 조회

예시 3: 특정 주차장의 구독권만 조회

GET /api/payments/orders/admin/member-purchases?memberId=12345&createdAtFrom=20260101&createdAtTo=20261231&type=SUBSCRIPTION&parkingLotId=PLOT001

→ PLOT001 주차장의 구독권만 조회

예시 4: 완료된 주문만 조회

GET /api/payments/orders/admin/member-purchases?memberId=12345&createdAtFrom=20260101&createdAtTo=20261231&scope=COMPLETED

→ 만료되었거나 전액 환불된 주문만 조회

2. 티켓별 구매내역 조회 API

한 줄 요약: 관리자가 특정 티켓(주차권/정기권)의 전체 구매 내역을 조회 (숨김 처리된 주문 포함)

🚀 빠른 시작

요청 예시 - 주차권 조회 (ticketType=PARKING)

GET /api/payments/orders/admin/ticket-purchases?ticketId=PT00010925&ticketType=PARKING&createdAtFrom=20260101&createdAtTo=20261231
Authorization: Bearer {관리자_토큰}

요청 예시 - 정기권/구독권 조회 (ticketType=REGULAR)

GET /api/payments/orders/admin/ticket-purchases?ticketId=RT00012345&ticketType=REGULAR&createdAtFrom=20260101&createdAtTo=20261231&scope=ONGOING
Authorization: Bearer {관리자_토큰}

응답 예시

{
  "success": true,
  "errorCode": null,
  "message": null,
  "timestamp": "2026-04-01T10:30:45",
  "data": {
    "content": [
      {
        "orderId": "ORD20260401123456",
        "parkingTicketId": "PT00010925",
        "type": "PARKING",
        "orderStatus": "AVAILABLE",
        "paymentStatus": "PAID",
        "finalPrice": 50000,
        "paymentAmt": 49500,
        "startDateAt": "2026-04-01T09:00:00",
        "endDateAt": "2026-04-01T18:00:00",
        "userInfo": {
          "userId": "user456",
          "name": "김철수",
          "email": "kim@example.com",
          "phoneNumber": "010-9876-5432"
        }
      }
    ],
    "pageNumber": 0,
    "pageSize": 20,
    "totalElements": 50,
    "totalPages": 3,
    "last": false
  }
}

📋 상세 정보

기본 정보

HTTP 메서드: GET
URL: /api/payments/orders/admin/ticket-purchases
인증: Bearer Token 필요 (관리자 권한)
특징: isHidden 필터가 적용되지 않아, 숨김 처리된 주문도 모두 조회됩니다.

요청 파라미터

필수 파라미터:

파라미터	타입	설명	가능한 값
ticketId	String	조회할 티켓의 ID	-
ticketType	String	티켓 유형	`PARKING` (주차권) / `REGULAR` (일반 정기권 + 구독권)
createdAtFrom	String	구매일 시작 날짜 (KST 기준, 형식: yyyyMMdd)	-
createdAtTo	String	구매일 종료 날짜 (KST 기준, 형식: yyyyMMdd)	-

선택 파라미터:

파라미터	타입	기본값	설명	가능한 값
scope	String	ALL	주문 범위 필터	`ALL` (모든 주문) / `ONGOING` (진행 중인 주문 - 티켓이 만료되지 않았고, 전액 환불되지 않은 주문) / `COMPLETED` (완료된 주문 - 티켓이 만료되었거나, 전액 환불된 주문)
page	Integer	0	페이지 번호 (0부터 시작)	-
size	Integer	20	페이지 크기	-

ticketId 설명:

티켓 유형	매칭 테이블	예시
주차권	parking_ticket.gds_id	PT00010925
정기권/구독권	regular_ticket.gds_id	RT00012345

응답 구조

응답의 data.content 배열에는 OrderInfo 객체가 포함됩니다. (상세 구조는 공통 응답 구조 참조)

{
  "success": true,
  "data": {
    "content": [/* OrderInfo 배열 */],
    "pageNumber": 0,
    "pageSize": 20,
    "totalElements": 50,
    "totalPages": 3,
    "last": false
  }
}

📚 추가 사용 예시

예시 1: 주차권 전체 구매내역 조회

GET /api/payments/orders/admin/ticket-purchases?ticketId=PT00010925&ticketType=PARKING&createdAtFrom=20260101&createdAtTo=20261231

→ 주차권 PT00010925의 전체 구매내역 조회

예시 2: 정기권 진행 중인 주문만 조회

GET /api/payments/orders/admin/ticket-purchases?ticketId=RT00012345&ticketType=REGULAR&createdAtFrom=20260101&createdAtTo=20261231&scope=ONGOING

→ 정기권 RT00012345의 진행 중인 주문만 조회 (일반 정기권+구독권 모두 포함)

예시 3: 정기권 완료된 주문만 조회

GET /api/payments/orders/admin/ticket-purchases?ticketId=RT00012345&ticketType=REGULAR&createdAtFrom=20260101&createdAtTo=20261231&scope=COMPLETED

→ 정기권 RT00012345의 만료되었거나 전액 환불된 주문만 조회

예시 4: 최근 30일 주차권 판매 내역

GET /api/payments/orders/admin/ticket-purchases?ticketId=PT00010925&ticketType=PARKING&createdAtFrom=20260301&createdAtTo=20260331&page=0&size=50

→ 3월 한 달간의 주차권 판매 내역 50개씩 조회

3. 공통 응답 구조 (OrderInfo DTO)

OrderInfo 객체는 주문의 전체 정보를 담고 있으며, 다음 섹션으로 구성됩니다:

기본 주문 정보

{
  "orderId": "ORD20260401123456",
  "parkingLotId": "PLOT001",
  "parkingTicketId": "PT00010925",
  "pricePerCar": 50000,
  "carCount": 2,
  "subPrice": 100000,
  "finalPrice": 95000,
  "truncatedAmt": 500,
  "paymentAmt": 94500,
  "userId": "user123",
  "startDate": "20260401",
  "startTime": "0900",
  "endDate": "20260501",
  "startDateAt": "2026-04-01T00:00:00",
  "endDateAt": "2026-05-01T23:59:59",
  "createdAt": "2026-04-01T02:30:00",
  "createdBy": "user123",
  "updatedAt": "2026-04-01T02:35:00",
  "updatedBy": "admin001",
  "createdById": 12345,
  "memberId": 67890,
  "memberUnitId": 11111
}

필드	설명
orderId	주문 ID
parkingLotId	주차장 ID
parkingTicketId	주차권/정기권 ID
pricePerCar	차량당 가격
carCount	차량 수
subPrice	소계 (pricePerCar × carCount)
finalPrice	최종 금액 (할인 적용 후)
truncatedAmt	절삭 금액 (1~99원 절삭)
paymentAmt	실제 결제 금액 (finalPrice - truncatedAmt)
userId	사용자 ID
startDate	시작일 (yyyyMMdd)
startTime	시작 시간 (HHmm)
endDate	종료일 (yyyyMMdd)
startDateAt	시작 일시 (UTC)
endDateAt	종료 일시 (UTC)
createdAt	주문 생성 일시 (UTC)
createdBy	생성자 ID
updatedAt	수정 일시 (UTC)
updatedBy	수정자 ID
createdById	생성자 내부 ID
memberId	회원 내부 ID
memberUnitId	회원 동호수 ID

주문 상태 정보

{
  "orderStatus": "AVAILABLE",
  "paymentStatus": "PAID",
  "approvalStatus": "APPROVED",
  "refundStatus": "NONE",
  "type": "REGULAR"
}

필드	설명
orderStatus	통합 주문 상태 (Enum 참조)
paymentStatus	결제 상태 (Enum 참조)
approvalStatus	승인 상태 (Enum 참조)
refundStatus	환불 상태 (Enum 참조)
type	주문 유형 (Enum 참조)

주문 속성

{
  "approvalRequired": true,
  "isInternal": true,
  "isNew": false,
  "buildingDong": "101동",
  "unitNumber": "1502호"
}

필드	설명
approvalRequired	승인 필요 여부
isInternal	내부 정기권 여부
isNew	신규상품 여부
buildingDong	건물 동 (내부 정기권인 경우)
unitNumber	호수 (내부 정기권인 경우)

쿠폰 정보

{
  "couponId": 5678,
  "couponDiscountAmount": 5000
}

사용자 정보 (userInfo)

{
  "userInfo": {
    "userId": "user123",
    "name": "홍길동",
    "email": "hong@example.com",
    "phoneNumber": "010-1234-5678",
    "memberId": 67890,
    "memberCategory": "INDIVIDUAL",
    "memberType": "DIRECT",
    "status": "ACTIVE",
    "companyName": "주식회사 아마노",
    "businessNumber": "123-45-67890",
    "businessAddress": "서울시 강남구...",
    "businessPhone": "02-1234-5678",
    "refundAccount": {
      "accountId": 9999,
      "bankCode": "004",
      "bankName": "국민은행",
      "accountNumber": "123456789012",
      "accountHolder": "홍길동",
      "refundBankFileId": 8888
    }
  }
}

회원 분류:

필드	값	설명
memberCategory	INDIVIDUAL	개인
memberCategory	CORPORATE	법인
memberType	DIRECT	직접 가입
memberType	SOCIAL	소셜 로그인
status	ACTIVE	활성
status	INACTIVE	비활성
status	SUSPENDED	정지
status	DELETED	탈퇴/삭제

법인 회원 정보: memberCategory = CORPORATE인 경우 포함

필드	설명
companyName	회사명
businessNumber	사업자번호
businessAddress	사업장 주소
businessPhone	사업장 전화번호

주차장 정보 (parkingLotInfo)

{
  "parkingLotInfo": {
    "plotId": "PLOT001",
    "plotName": "강남 타워 주차장",
    "plotAliasNm": "강남점",
    "address": "서울시 강남구 테헤란로 123"
  }
}

티켓 정보 (ticketInfo)

{
  "ticketInfo": {
    "ticketId": "PT00010925",
    "ticketName": "월 정기권",
    "ticketType": "REGULAR",
    "price": 50000,
    "maxCarCount": 2,
    "validPeriodDays": 30,
    "description": "월 단위 정기권"
  }
}

차량 정보 (cars)

{
  "cars": [
    {
      "groupId": 1,
      "carChain": [
        {
          "orderCarId": 101,
          "carNumber": "12가3456",
          "carModel": "소나타",
          "carType": "SEDAN",
          "createdAt": "2026-04-01T02:30:00",
          "createdBy": "user123",
          "isActive": false,
          "replacedAt": "2026-04-15T10:00:00"
        },
        {
          "orderCarId": 102,
          "carNumber": "34나5678",
          "carModel": "그랜저",
          "carType": "SEDAN",
          "createdAt": "2026-04-15T10:00:00",
          "createdBy": "user123",
          "isActive": true
        }
      ]
    }
  ]
}

차량 변경 이력이 체인 형태로 포함되며, isActive: true인 항목이 현재 활성 차량입니다.

결제 정보 (paymentInfo)

{
  "paymentInfo": {
    "moid": "PAY20260401123456",
    "orderId": "ORD20260401123456",
    "payMethod": "CARD",
    "amount": 94500,
    "goodsName": "월 정기권 2대",
    "status": "PAID",
    "authCode": "12345678",
    "authDate": "20260401",
    "createdAt": "2026-04-01T02:30:00",
    "paidAt": "2026-04-01T02:30:15",
    "cardName": "신한카드",
    "cardNum": "1234-****-****-5678",
    "receiptType": "CASH",
    "receiptStatus": "SUCCESS",
    "cardInfo": {
      "cardCode": "04",
      "cardName": "신한카드",
      "cardNo": "1234********5678",
      "cardQuota": "00",
      "cardInterest": "N"
    },
    "cashReceiptInfo": {
      "receiptType": "PERSONAL",
      "receiptNumber": "010-1234-5678",
      "approvalNumber": "98765432",
      "issuedAt": "2026-04-01T02:30:45"
    }
  }
}

결제 수단:

값	설명
CARD	카드
BILLING	빌링
CASH	현금/계좌이체

영수증 유형:

값	설명
CASH	현금영수증
TAX_INVOICE	세금계산서
NONE	영수증 미발급

환불 정보 (refundInfo)

{
  "refundInfo": {
    "totalRefundAmount": 40000,
    "refundCount": 1,
    "latestRefundDate": "2026-04-20T05:30:00",
    "refundStatus": "COMPLETED",
    "refundDetails": [
      {
        "refundId": "REF20260420112233",
        "refundAmount": 40000,
        "refundMethod": "CARD_CANCEL",
        "refundedAt": "2026-04-20T05:30:00",
        "refundReason": "중도 해지"
      }
    ],
    "refundApprovalHistory": [
      {
        "id": 555,
        "isForceRefund": false,
        "requestInfo": {
          "requestedAt": "2026-04-20T02:00:00",
          "requestedBy": "user123",
          "requestReason": "사용하지 않음",
          "carDetails": [
            {
              "orderCarId": 101,
              "carNumber": "12가3456",
              "refundEndDate": "20260420",
              "refundReason": "중도 해지",
              "refundAmount": 40000
            }
          ]
        },
        "responseInfo": {
          "responseStatus": "APPROVED",
          "processedAt": "2026-04-20T03:00:00",
          "processedBy": "admin001",
          "approvalDetails": {
            "refundMethod": "CARD_CANCEL",
            "totalRefundAmount": 40000
          }
        }
      }
    ]
  }
}

환불 요청부터 승인까지의 전체 이력이 포함됩니다.

구독 정보 (subscriptionInfo)

type=SUBSCRIPTION인 경우만 포함

{
  "subscriptionInfo": {
    "subscriptionId": "SUB20260401123456",
    "billingKey": "BK1234567890",
    "subscriptionStatus": "ACTIVE",
    "nextBillingDate": "2026-05-01",
    "billingCycle": "MONTHLY",
    "lastPaymentDate": "2026-04-01",
    "lastPaymentStatus": "SUCCESS"
  }
}

승인 정보 (approvalInfo)

approvalRequired=true인 경우만 포함

{
  "approvalInfo": {
    "approvalId": 777,
    "approvalStatus": "APPROVED",
    "requestedAt": "2026-04-01T02:30:00",
    "requestedBy": "user123",
    "approvedAt": "2026-04-01T10:00:00",
    "approvedBy": "admin001",
    "approvalMessage": "승인 완료"
  }
}

쿠폰 상세 정보 (couponInfo)

{
  "couponInfo": {
    "couponId": 5678,
    "couponName": "신규가입 할인",
    "couponDiscountAmount": 5000,
    "validFrom": "2026-03-01T00:00:00",
    "validUntil": "2026-12-31T23:59:59"
  }
}

4. Enum 상태값 정의

OrderStatus - 통합 주문 상태

주문의 전체 상태를 나타내는 통합 상태값입니다.
payment_status, approval_status, refund_status로부터 계산됩니다.

우선순위 높음 (문제 상태):

상태	설명
REFUNDED	전액 환불 완료
PARTIALLY_REFUNDED	부분 환불 완료

우선순위 중간 (거절/실패):

상태	설명
PAYMENT_FAILED	결제 실패
REFUND_REJECTED	환불 거절
APPROVAL_REJECTED	승인 거절

우선순위 낮음 (대기 중):

상태	설명
REFUND_PENDING	환불 대기
APPROVAL_PENDING	승인 대기
PAYMENT_PENDING	결제 대기

정상 상태:

상태	설명
AVAILABLE	사용 가능 (정기권)
PAYMENT_DELAYED	구독 결제 지연

Deprecated (하위 호환용):

상태	설명
PAID	구버전 호환용 - AVAILABLE과 동일하게 처리
PENDING	구버전 호환용 - PAYMENT_PENDING과 동일하게 처리

상태 계산 우선순위:

순위	조건	결과 상태
1	refundStatus가 COMPLETED	REFUNDED
2	refundStatus가 PARTIALLY_COMPLETED	PARTIALLY_REFUNDED
3	paymentStatus가 FAILED	PAYMENT_FAILED
4	refundStatus가 REJECTED	REFUND_REJECTED
5	approvalStatus가 REJECTED	APPROVAL_REJECTED
6	refundStatus가 REQUESTED	REFUND_PENDING
7	approvalStatus가 REQUESTED	APPROVAL_PENDING
8	paymentStatus가 PENDING	PAYMENT_PENDING
9	구독 결제 지연 확인	PAYMENT_DELAYED
10	그 외	AVAILABLE

PaymentStatus - 결제 상태

주문의 결제 진행 상태를 나타냅니다.

상태	설명
PENDING	결제 대기 - 주문 생성 후 결제가 진행되지 않은 상태
PAID	결제 완료 - 결제가 정상적으로 완료된 상태
FAILED	결제 실패 - 카드 승인 거부, 한도 초과, 네트워크 오류 등

ApprovalStatus - 승인 상태

승인이 필요한 주문의 승인 진행 상태를 나타냅니다.

상태	설명
NONE	승인 불필요 - approvalRequired=false인 주문
REQUESTED	승인 요청 - 관리자의 승인 대기 중
APPROVED	승인 완료 - 주문 사용 가능
REJECTED	승인 거절 - 주문 사용 불가

RefundStatus - 환불 상태

주문의 환불 진행 상태를 나타냅니다.

상태	설명
NONE	환불 없음 - 환불 요청이 없는 정상 주문
REQUESTED	환불 요청 - 관리자의 환불 승인 대기 중
REJECTED	환불 거절 - 주문은 계속 유효
PARTIALLY_COMPLETED	부분 환불 완료 - 일부 차량에 대해서만 환불 완료 (예: 2대 구매 중 1대만 환불)
COMPLETED	전체 환불 완료 - 모든 차량 환불, 주문 완전 취소

OrderType - 주문 유형

주문의 상품 유형을 나타냅니다.

유형	설명
REGULAR	일반 정기권 - 월/분기/연 단위, 1회 결제로 일정 기간 사용
SUBSCRIPTION	구독권 - 자동 갱신, 정해진 주기마다 자동 결제 (billingKey 사용)
PARKING	주차권 - 단기 주차권 (시간/일 단위)

참고: 아마노 비즈니스 관점에서 REGULAR와 SUBSCRIPTION은 동일한 상품이며, 같은 regular_ticket 테이블을 사용합니다.

MemberCategory - 회원 카테고리

UserInfo에서 사용되는 회원 구분입니다.

카테고리	설명
INDIVIDUAL	개인 회원 - 일반 개인 사용자
CORPORATE	법인 회원 - 기업/단체, companyName, businessNumber 등 법인 정보 포함

MemberType - 가입 유형

UserInfo에서 사용되는 회원 가입 방식입니다.

유형	설명
DIRECT	직접 가입 - 이메일/비밀번호로 가입
SOCIAL	소셜 로그인 가입 - 카카오, 네이버 등 소셜 계정

MemberStatus - 회원 상태

UserInfo에서 사용되는 회원 활성화 상태입니다.

상태	설명
ACTIVE	활성 상태 - 정상적으로 서비스 이용 가능
INACTIVE	비활성 상태 - 휴면 계정 등
SUSPENDED	정지 상태 - 관리자에 의해 이용 정지
DELETED	탈퇴/삭제 상태 - 회원 탈퇴 처리

참고 사항

1. 날짜/시간 처리

요청 파라미터의 날짜는 KST(한국 시간) 기준
날짜 형식은 yyyyMMdd (예: 20260101)
응답 데이터의 LocalDateTime은 모두 UTC 기준
createdAtFrom은 해당 날짜의 00:00:00(KST)로 변환
createdAtTo는 해당 날짜의 23:59:59(KST)로 변환

2. N+1 쿼리 방지

주차장 정보: 페이지 내 모든 주문의 주차장을 일괄 조회
사용자 정보: 페이지 내 모든 주문의 회원을 일괄 조회
성능 최적화를 위해 배치 조회 패턴 적용

3. 관리자 전용 API

isHidden 필터가 적용되지 않음
사용자가 숨김 처리한 주문도 모두 조회됨
관리 목적으로 모든 주문 내역을 확인할 수 있음

4. ticketType=REGULAR의 특수성

REGULAR 선택 시 정기권(REGULAR)과 구독권(SUBSCRIPTION) 모두 조회
아마노 비즈니스 모델에서 두 상품은 같은 테이블(regular_ticket) 사용
실제 주문 유형은 응답의 type 필드로 구분 가능

5. scope 필터의 활용

ONGOING: 현재 활성화된 주문 파악에 유용 (고객 CS, 환불 가능 여부 확인)
COMPLETED: 종료된 주문 통계/분석에 유용
ALL: 전체 이력 조회 시 사용

6. 에러 처리

400 Bad Request: 파라미터 검증 실패
200 OK with error response: 시스템 에러
모든 에러 응답은 ApiResponse 형식으로 통일

7. 페이징

page는 0부터 시작 (첫 페이지 = 0)
기본 페이지 크기는 20
totalElements로 전체 건수 확인 가능

문서 버전: 1.0
작성일: 2026-04-01