PaymentService 관리자 메뉴 설계서

AKC B2C의 결제/주문 도메인을 운영자가 효율적으로 관리할 수 있도록, PaymentService를 중심으로 관리자 페이지 메뉴와 API 요구사항을 정의합니다.
소비자용 API와의 연계를 기반으로, Admin 전용 기능 및 워크플로우를 제안합니다.

참고: 소비자용 주문/결제 주요 엔드포인트는 OrderController에 정의되어 있습니다.

• 파일: PaymentService/src/main/java/com/akc/b2c/paymentservice/controller/OrderController.java

목차

• PaymentService 관리자 메뉴 설계서
  • 목차
  • 1. 주문 승인/거부 관리
  • 2. 환불 관리
  • 3. 결제 트랜잭션 관리
  • 4. 구독 관리
  • 5. 영수증/현금영수증/세금계산서 관리
  • 6. 정산/매출 리포트
  • 7. 견적서 관리
  • 8. 실패/예외 모니터링
  • 9. 감사 로그(Audit) 및 타임라인
  • Admin 전용 API 요약(제안)

1. 주문 승인/거부 관리

• 목적

  • 소비자가 생성한 승인 요청 큐를 처리하여 주문을 승인하거나 거부
  • 금액/정책 검증 후 내부 메모와 사유를 남김

• 주요 화면

  1. 승인 대기 목록
     • 필터: 주차장, 주문유형(REGULAR/SUBSCRIPTION/PARKING), 결제수단, 금액 범위, 요청일자, 사용자, 상태(PENDING_APPROVAL)
     • 컬럼: 주문ID, 사용자, 주차장/상품, 금액, 요청일시, 현재상태, 메모 유무
  2. 상세 보기
     • 주문 기본 정보 + 차량 목록
     • 결제 예정 정보/가격 검증 결과 호출 버튼
     • 승인/거부 액션(사유, 내부 메모 입력)

• 상태 전이(예시)

  • PENDING_APPROVAL → APPROVED → (결제 진행) → PAID
  • PENDING_APPROVAL → REJECTED

• 감사

  • 모든 승인/거부 액션은 감사로그에 기록(누가, 언제, 무엇을, 사유)

• 관련 소비자 API(참고)

  • POST /api/payments/orders/{orderId}/approval-requests (승인 요청)
  • POST /api/payments/orders/{orderId}/approval-rerequests (재요청)

• 필요 Admin API(제안)

  • GET /api/admin/payments/orders/approval-queue
  • POST /api/admin/payments/orders/{orderId}/approve (body: memo)
  • POST /api/admin/payments/orders/{orderId}/reject (body: reason, memo)

• 운영 필드(권장)

  • approverId, approvedAt, rejectedAt, rejectReason, adminMemo

• 예외/엣지

  • 이미 APPROVED/REJECTED 상태 재처리 방지
  • 가격 검증 실패 시 승인 차단 옵션
  • 사용자 재요청과 교차 타이밍 경쟁 제어(낙관적 잠금/상태 체크)

2. 환불 관리

• 목적

  • 주문 단위 환불 요청 접수/승인/거절 처리
  • 부분 환불 가능 정책 지원, 전표/영수증 처리 연동

• 주요 화면

  1. 환불 대기 목록
     • 필터: 주차장, 주문ID, 차량번호, 요청사유, 요청일자, 상태(REFUND_REQUESTED)
     • 컬럼: 주문ID, 차량번호, 금액(가능/요청/예상환불), 요청사유, 요청일시
  2. 상세 보기
     • 기존 결제 트랜잭션/승인번호, 환불 가능액, 수수료 정책
     • 승인/거절(사유) 및 부분 금액 입력

• 상태 전이(예시)

  • REFUND_REQUESTED → REFUND_APPROVED → REFUNDED
  • REFUND_REQUESTED → REFUND_REJECTED

• 감사

  • 환불 결정/금액/사유 로그 기록

• 예외/엣지

  • PG 환불 실패 시 재시도/보류, 부분 환불 합계 검증, 이미 환불 완료 건 재처리 방지
  • USED 상태 환불 정책(부분/불가) 반영

3. 결제 트랜잭션 관리

• 목적

  • 결제 시도/성공/실패 이력을 조회하고, 수동 캡처/취소/재시도 등 운영 개입

• 주요 화면

  • 트랜잭션 목록: 상태(AUTHORIZED/CAPTURED/VOID/FAILED), 수단, PG사, 금액, 기간
  • 상세: 승인번호, 원거래ID, 실패코드/메시지, 영수증 링크
  • 액션: 캡처, 취소(VOID/REFUND), 재시도

4. 구독 관리

• 목적

  • 활성/만료 예정 구독 조회, 해지/연장

• 주요 화면

  • 구독 목록(활성/만료예정/만료)
  • 상세: 차량, 변경 이력, 결제/환불 히스토리
  • 액션: 해지, 연장

• 예외/엣지

  • 사용기간 경과/개시 전 정책, 중도해지 환불 계산

5. 영수증/현금영수증/세금계산서 관리

• 목적

  • 영수증(증빙용), 현금영수증, 세금계산서 발행 신청/재전송/취소 및 상태 조회
  • 현금영수증/세금계산서는 외부 API에 "신청만" 수행하며, 실제 발행되었는지 여부를 동기화 해야하는지는 미정.

• 주요 화면

  • 발행 이력: 유형(증빙/현금/세금), 상태(신청/발행/취소/실패), 고객 연락처
  • 액션: 발행(또는 발행 신청), 재전송, 취소

• 예외/엣지

  • PG/현금영수증 발행 실패 재시도, 국세청 연동 지연 케이스 핸들링

6. 정산/매출 리포트

• 목적

  • 기간/주차장/상품/결제수단 별 매출·환불 집계 및 내보내기

• 주요 화면

  • 일/주/월 집계, 드릴다운(주차장/상품)
  • CSV/XLS 내보내기

• 지표 정의(예)

  • 총매출, 환불액, 순매출, 수수료, 미수/보류

7. 견적서 관리

• 목적

  • 견적서 번호(quote_no)를 서버(DB)에서 발급/저장하고, 견적서 기반 주문 전환을 지원

• 주요 화면

  • 견적 목록/상세(상태: DRAFT/ISSUED/EXPIRED/CONVERTED/CANCELED)
  • 액션: 조회/다운로드, 재전송, 재랜더(서버 템플릿 기반), 무효 처리(사유)

• 정책/모델(요약)

  • quote_no는 고유 일련번호(예: Q-YYYY-MM-######)로 서버에서 생성/보관
  • 가격 스냅샷(JSON)과 템플릿 버전을 함께 저장하여 동일 출력 재현
  • 템플릿은 서버에서 버전 관리하며, 렌더링도 서버에서 수행(프론트는 뷰어/전달 역할)
  • 견적은 주문 생성 시 자동 발급되며, 만료일 보정 기능은 제공하지 않음

8. 실패/예외 모니터링

• 목적

  • 결제/웹훅/동기화 실패를 유형별로 수집, 재시도/무시 처리

• 주요 화면

  • 실패 큐: 유형, 에러코드, 최초/최종 발생, 재시도 횟수
  • 액션: 재시도, 무시, 메모

9. 감사 로그(Audit) 및 타임라인

• 목적

  • 주문/결제/환불/승인 등 이벤트 타임라인으로 추적

• 주요 화면

  • 타임라인: at, actor(USER/ADMIN/SYSTEM), action, details, memo
  • 필터: 주문ID, 기간, actorType, action

Admin 전용 API 요약(제안)

• 주문 승인/거부

  • 승인 대기 목록 조회: GET /api/admin/payments/orders/approval-queue?status=PENDING_APPROVAL&parkingLotId=&type=&from=&to=&q=
  • 주문 승인: POST /api/admin/payments/orders/{orderId}/approve
    • body: { "memo": "string" }
    • result: { "status": "APPROVED", "approvedAt": "...", "approverId": "..." }
  • 주문 거절: POST /api/admin/payments/orders/{orderId}/reject
    • body: { "reason": "string", "memo": "string" }
    • result: { "status": "REJECTED", "rejectedAt": "...", "approverId": "...", "reason": "..." }

• 환불

  • 환불 요청 목록 조회: GET /api/admin/payments/refunds?status=REFUND_REQUESTED&parkingLotId=&from=&to=&q=
  • 차량 환불 승인: POST /api/admin/payments/orders/{orderId}/cars/{orderCarId}/refund-approve
    • body: { "amount": 10000, "reason": "string" } (amount 생략 시 전액)
  • 차량 환불 거절: POST /api/admin/payments/orders/{orderId}/cars/{orderCarId}/refund-reject
    • body: { "reason": "string" }

• 결제 트랜잭션

  • 결제 트랜잭션 목록 조회: GET /api/admin/payments/transactions?status=&method=&pg=&from=&to=&q=
  • 결제 캡처(매입): POST /api/admin/payments/transactions/{paymentId}/capture
  • 결제 취소(VOID): POST /api/admin/payments/transactions/{paymentId}/void
  • 결제 재시도: POST /api/admin/payments/transactions/{paymentId}/retry

• 구독

  • 구독 목록 조회: GET /api/admin/payments/subscriptions?status=&parkingLotId=&from=&to=&q=
  • 구독 해지: POST /api/admin/payments/subscriptions/{subscriptionId}/cancel
  • 구독 기간 연장: POST /api/admin/payments/subscriptions/{subscriptionId}/extend

• 영수증

  • 영수증 이력 조회: GET /api/admin/payments/receipts?orderId=&type=CARD|CASH|TAX&status=&from=&to=
  • 영수증 발행: POST /api/admin/payments/orders/{orderId}/receipts/issue
  • 영수증 재전송: POST /api/admin/payments/orders/{orderId}/receipts/resend
  • 영수증 취소: POST /api/admin/payments/orders/{orderId}/receipts/cancel

• 견적서

  • 견적 목록 조회: GET /api/admin/payments/quotes?orderId=&quoteNo=&status=
  • 견적 조회: GET /api/admin/payments/quotes/{quoteNo}
  • 견적 재전송: POST /api/admin/payments/quotes/{quoteNo}/resend
  • 견적 재렌더: POST /api/admin/payments/quotes/{quoteNo}/rerender
  • 견적 무효 처리: POST /api/admin/payments/quotes/{quoteNo}/invalidate

• 리포트/정산

  • 매출 리포트 조회(기간): GET /api/admin/payments/reports/sales?from=&to=
  • 주차장별 리포트 조회: GET /api/admin/payments/reports/by-parking-lot?from=&to=
  • 리포트 CSV 내보내기: GET /api/admin/payments/reports/export.csv?from=&to=

• 실패/예외

  • 실패 이벤트 목록 조회: GET /api/admin/payments/errors?type=&code=&from=&to=
  • 실패 이벤트 재시도: POST /api/admin/payments/errors/{errorId}/retry

• 타임라인

  • 주문 타임라인 조회: GET /api/admin/payments/orders/{orderId}/timeline