[FEAT] 정산 - 정산 예정 금액 API 및 Payple 정산내역 조회 인프라 (#479)

[minij02]

Summary

정산관리 화면 대시보드의 "정산 예정 금액"을 위한 신규 API와, 향후 정산 완료 동기화/환불/리포트에 재사용할 Payple 정산내역 조회 인프라를 추가.

핵심 변경

• GET /api/settlements/pending-amount 신규 — Settlement.status='Pending' 행의 amount 합계 + 건수 반환
  • prisma.settlement.aggregate로 단일 쿼리, rate-limit 무관
• utils/payple-settlement.ts 신규 (내부 유틸)
  • fetchPaypleSettlementAuth: PCD_SETTLEMENT_FLAG=Y 파트너 인증, AuthKey/PAY_HOST/PAY_URL을 Redis에 25분 캐시
  • fetchPaypleSettlements: 정산내역 조회, PCD_HAS_MORE / PCD_LASTKEY 페이지네이션 처리
  • 본 PR엔 외부 endpoint 노출 없음

⚠️ 발견된 갭 (별도 이슈 분리 필요)

코드 점검 결과 Settlement.status를 Succeed로 업데이트하는 로직이 어디에도 없음. 결제 완료 시 purchase.complete.service.ts / purchase.webhook.service.ts에서 status='Pending'으로만 생성됨. 따라서:

• 현재 GET /pending-amount는 모든 미정산 거래의 누계가 반환됨 (정산이 실제로 완료됐는지와 무관)
• 정확한 "정산 예정 금액"이 되려면 본 PR의 fetchPaypleSettlements를 활용해 PCD_SETTLE_DATE 기준 동기화하는 스케줄러/Webhook 처리가 필요

→ 별도 이슈로 분리해 정산 완료 처리 흐름 구현 권고.

환경변수

PAYPLE_SETTLEMENT_AUTH_PATH=/php/auth.php   # 기본값. 실제 경로는 sandbox 검증 후 정정

(PAYPLE_CPAY_URL, PAYPLE_CST_ID, PAYPLE_CUST_KEY는 기존 사용)

API 변경 (프론트엔드 동기화)

항목	변경
GET /api/settlements/pending-amount	신규 — 응답 { message, pending_amount, pending_count, statusCode }

Test plan

• pnpm build / pnpm tsc --noEmit 통과
• GET /pending-amount 응답 동작 확인 (Settlement 행 있는 사용자/없는 사용자)
• Payple sandbox에서 fetchPaypleSettlementAuth 호출 성공 확인 (PAYPLE_SETTLEMENT_AUTH_PATH 정정)
• fetchPaypleSettlements 페이지네이션 동작 sandbox 검증 (PCD_HAS_MORE=true 케이스)
• 프론트 통합 후 머지

Closes #479