Site Review - Phase 3 놀고팜 + 고향사랑기부 통합 리뉴얼

기능 요구 사항 및 API 명세

🧩 Functional Requirements & APIs 🌐 HTTP RESTful API JSON 스키마 규격 ⚠️ 에러 핸들링 정책 및 UI 대응 테이블

본 문서에서는 백엔드와 프론트엔드가 데이터를 통신하기 위한 세부 API의 HTTP 헤더, 질의 파라미터, JSON 스키마 구조 및 유효성 검증 정책을 다룹니다.

1. API: 기부 한도 및 적합성 검증 (`GET`)

기부 화면 진입 시 로그인 사용자의 거주지 지자체 기부 제한과 연간 잔여 기부 한도를 일괄 조회합니다.

🌐 GET `/api/v1/donations/eligibility`

Query Parameter: `targetGovCode` (string, 필수 - 10자리 지자체 코드)
Headers: `Authorization: Bearer {jwt}`

🟢 Response (HTTP 200 OK)
{
  "isEligible": true,
  "legalRegionCode": "1114000000",
  "remainingLimit": 19500000,
  "message": "기부 가능 지자체/한도입니다."
}

2. API: 통합 결제 오케스트레이션 (`POST`)

장바구니 복합 주문(체험 예약권 + 기부 답례품)을 처리하기 위한 Saga 오케스트레이션 최종 승인 요청입니다.

🌐 POST `/api/v1/orders/pay`
{
  "cartIdxList": [102, 103],
  "paymentMethod": "CARD",
  "totalAmount": 130000,
  "pgPayAmount": 30000,
  "donationAmount": 100000,
  "donationItems": [
    { "localGovCode": "4571000000", "projectIdx": 12 }
  ]
}
🟢 Response (HTTP 200 OK)
{
  "orderIdx": 90124,
  "status": "COMPLETED",
  "pgTid": "pg_approve_tx_998124",
  "eumApprovalNo": "eum_app_no_20260626001",
  "gpointEarned": 30000
}

3. 에러 코드 대응 매핑 테이블

에러 코드 (errorCode) HTTP Status 발생 조건 프론트엔드 예외 처리 대응 방침
`ERR_LIMIT_EXCEEDED` 400 Bad Request 연 2,000만 원 기부 한도액 초과 "연간 기부 한도를 초과했습니다." 경고 팝업 활성화 후 결제 프로세스 즉시 중단
`ERR_SAME_REGION` 400 Bad Request 거주 지자체로 기부 시도 "거주 지자체에는 기부할 수 없습니다." 안내 및 기부 입력 폼 강제 비활성화
`ERR_SAGA_PG_FAILED` 502 Bad Gateway 기부 e음 API는 승인되었으나 일반 예약 PG사 결제가 최종 실패 e음 취소 API 즉시 자동 백그라운드 호출(Saga 롤백) 후, 사용자에게 "카드 승인 실패로 기부가 환불되었습니다" 노출
📑 작성 AI