diff --git a/docs/20260929_크리에이터_선물하기/prd.md b/docs/20260929_크리에이터_선물하기/prd.md index 6a559c83..1d148d04 100644 --- a/docs/20260929_크리에이터_선물하기/prd.md +++ b/docs/20260929_크리에이터_선물하기/prd.md @@ -246,6 +246,7 @@ INSPECTION_COMPLETED -> UNDELIVERABLE | `GIFT-011` | 확정 | 팬/크리에이터 대상 푸시를 상태별로 분리 발송한다 | 각 상태 전이에서 지정된 수신자에게만 지정 문구와 딥링크가 발송된다 | `P7` | | `GIFT-012` | 확정 | 관리자는 카테고리를 등록/수정/논리삭제할 수 있다 | 삭제는 `isActive=false`만 수행한다 | `P1` | | `GIFT-013` | 확정 | 관리자는 사이즈별 가격을 수정할 수 있다 | 새 신청에는 변경 가격이 적용되고 기존 신청 스냅샷은 바뀌지 않는다 | `P1` | +| `GIFT-015` | 확정 | 관리자는 전체 선물함 목록과 상세를 조회하고 현재 상태에서 가능한 운영 액션을 확인할 수 있다 | 목록은 상태/신청번호/닉네임 검색과 페이징을 지원하고, 상세는 발송인/수취인 개인정보와 상품/배송/상태 정보를 내려준다 | `P10` | ## 8. API 계약 @@ -715,7 +716,105 @@ Response: `salePriceCan`은 0보다 커야 하고 `basePriceCan`보다 클 수 없다. -### 8.13 운영 상태변경 API +### 8.13 관리자 선물함 조회 API + +관리자 페이지는 전체 선물함을 목록과 상세로 조회한다. 상태 변경은 `8.14 운영 상태변경 API`의 기존 전용 endpoint를 사용한다. + +#### 8.13.1 관리자 선물함 목록 조회 + +`GET /api/v2/admin/gifts?status=TRACKING_REGISTERED&applicationNo=A-100&nickname=fan&page=0&size=20` + +Query: + +| 이름 | 필수 | 설명 | +|---|---|---| +| `status` | 아니오 | 선물 상태. 지정하면 해당 상태만 조회 | +| `applicationNo` | 아니오 | 신청번호 부분 검색 | +| `nickname` | 아니오 | 발송인 또는 수취인 닉네임 부분 검색 | +| `page` | 아니오 | 0 기반 page index. 기본값 `0` | +| `size` | 아니오 | page size. 기본값 `20` | + +필터는 AND로 조합한다. `nickname`은 발송인 닉네임 또는 수취인 닉네임 중 하나에 포함되면 매칭한다. + +Response: + +```json +{ + "totalCount": 1, + "items": [ + { + "applicationNo": "A-1002609300001", + "senderNickname": "팬닉네임", + "recipientNickname": "크리에이터닉네임", + "sizeCode": "SMALL", + "sizeName": "소형", + "categoryName": "인형", + "classificationNumber": "100", + "courierCompanyName": "CJ대한통운", + "trackingNumber": "1234567890", + "status": "TRACKING_REGISTERED", + "statusName": "발송 확인", + "availableActions": ["ARRIVE_MAILBOX", "MARK_UNDELIVERABLE"] + } + ], + "page": 0, + "size": 20, + "hasNext": false +} +``` + +#### 8.13.2 관리자 선물 상세 조회 + +`GET /api/v2/admin/gifts/{applicationNo}` + +Response: + +```json +{ + "applicationNo": "A-1002609300001", + "senderInfo": { + "nickname": "팬닉네임", + "name": "홍길동", + "phoneNumber": "01012345678", + "address": "(06234) 서울시 강남구 ..., 101동 1001호" + }, + "recipientInfo": { + "nickname": "크리에이터닉네임", + "name": "김소다", + "phoneNumber": "01098765432", + "address": "(04524) 서울시 중구 ..., 202호" + }, + "productInfo": { + "sizeCode": "SMALL", + "sizeName": "소형", + "categoryName": "인형", + "classificationNumber": "100" + }, + "inboundDeliveryInfo": { + "courierCompanyName": "CJ대한통운", + "trackingNumber": "1234567890" + }, + "status": "TRACKING_REGISTERED", + "statusName": "발송 확인", + "availableActions": ["ARRIVE_MAILBOX", "MARK_UNDELIVERABLE"] +} +``` + +크리에이터가 배송지를 아직 입력하지 않은 경우에도 `recipientInfo.nickname`은 내려주고, `recipientInfo.name`, `recipientInfo.phoneNumber`, `recipientInfo.address`는 빈 문자열 `""`로 내려준다. + +`availableActions`는 현재 상태별로 다음 값만 내려준다. + +| 현재 상태 | availableActions | +|---|---| +| `RECEIVED` | `[]` | +| `TRACKING_REGISTERED` | `["ARRIVE_MAILBOX", "MARK_UNDELIVERABLE"]` | +| `ARRIVED_AT_MAILBOX` | `["COMPLETE_INSPECTION", "MARK_UNDELIVERABLE"]` | +| `INSPECTION_COMPLETED` | `["COMPLETE_DELIVERY", "MARK_UNDELIVERABLE"]` | +| `DELIVERED` | `[]` | +| `UNDELIVERABLE` | `[]` | +| `CANCELED` | `[]` | + +### 8.14 운영 상태변경 API | Method | Path | 이전 상태 | 변경 상태 | 필수 입력 | |---|---|---|---|---| @@ -732,7 +831,7 @@ Response: } ``` -### 8.14 자동 스케줄링 작업 +### 8.15 자동 스케줄링 작업 | 작업 | 대상 | 처리 | 푸시 | |---|---|---|---|