From 31406e7f0a84f0334cf9bc499b7b0d25565f5fa1 Mon Sep 17 00:00:00 2001 From: Klaus Date: Fri, 2 Oct 2026 11:34:05 +0900 Subject: [PATCH] =?UTF-8?q?docs(gift):=20=EC=82=AC=EC=84=9C=ED=95=A8=20?= =?UTF-8?q?=EB=85=B8=EC=B6=9C=20=EC=A1=B0=EA=B1=B4=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=EB=A5=BC=20=EA=B0=B1=EC=8B=A0=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../client-api-summary.md | 4 ++++ .../20260929_크리에이터_선물하기/plan-task.md | 19 +++++++++++++++---- docs/20260929_크리에이터_선물하기/prd.md | 7 ++++--- 3 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/20260929_크리에이터_선물하기/client-api-summary.md b/docs/20260929_크리에이터_선물하기/client-api-summary.md index 2031c594..ca271522 100644 --- a/docs/20260929_크리에이터_선물하기/client-api-summary.md +++ b/docs/20260929_크리에이터_선물하기/client-api-summary.md @@ -187,6 +187,10 @@ data class GiftMailboxResponse( val phoneNumber: String ) +// mailbox는 direction=SENT이고 status가 RECEIVED, TRACKING_REGISTERED, +// ARRIVED_AT_MAILBOX, INSPECTION_COMPLETED일 때만 값이 있다. +// DELIVERED, UNDELIVERABLE, CANCELED 또는 direction=RECEIVED이면 null이다. + data class GiftDeliveryInfoResponse( val canceledAt: String?, val undeliverableAt: String?, diff --git a/docs/20260929_크리에이터_선물하기/plan-task.md b/docs/20260929_크리에이터_선물하기/plan-task.md index 9b77549c..d0682ed6 100644 --- a/docs/20260929_크리에이터_선물하기/plan-task.md +++ b/docs/20260929_크리에이터_선물하기/plan-task.md @@ -1311,7 +1311,7 @@ P7은 FCM 확장 후 전체 상태 전이를 연결하고 최종 회귀로 종 ## Phase 11: 선물 받을 주소 설정 -**Phase 결과:** 관리자는 전역 단일 선물 받을 주소를 등록/수정하고, 팬은 운송장 등록 전 상세에서 해당 주소를 확인할 수 있다. +**Phase 결과:** 관리자는 전역 단일 선물 받을 주소를 등록/수정하고, 팬은 보낸 선물의 전달 완료 전 정상 진행 상세에서 해당 주소를 확인할 수 있다. **선행조건:** `P3-GATE`, `P10-GATE` 완료. @@ -1331,11 +1331,11 @@ P7은 FCM 확장 후 전체 상태 전이를 연결하고 최종 회귀로 종 #### Task 11.2 선물 상세 받을 주소 노출 구현 -**Goal 실행 `P11-T2`:** 보낸 선물의 운송장 등록 전 상세에만 받을 주소를 노출한다. +**Goal 실행 `P11-T2`:** 보낸 선물의 전달 완료 전 정상 진행 상세에만 받을 주소를 노출한다. - **Files:** Modify `GiftQueryService.kt`; Test `GiftQueryServiceTest.kt`, `GiftControllerTest.kt`. -- [x] **RED:** `direction=SENT`이고 `status=RECEIVED`인 상세만 `mailbox`를 반환하는 실패 test를 작성한다. -- [x] **RED:** 받을 주소 미등록 또는 다른 상태/방향이면 `mailbox=null`인 실패 test를 작성한다. +- [x] **RED:** `direction=SENT`이고 `status`가 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`인 상세에서 `mailbox`를 반환하는 실패 test를 작성한다. +- [x] **RED:** 받을 주소 미등록, 종료 상태(`DELIVERED`, `UNDELIVERABLE`, `CANCELED`), 또는 다른 방향이면 `mailbox=null`인 실패 test를 작성한다. - [x] **RED 확인:** focused test 실패를 확인한다. - [x] **GREEN:** `GiftQueryService`에서 받을 주소 repository를 조회해 기존 `GiftMailboxResult`로 매핑한다. - [x] **GREEN 확인:** focused test 통과를 확인한다. @@ -1351,6 +1351,17 @@ P7은 FCM 확장 후 전체 상태 전이를 연결하고 최종 회귀로 종 **Expected:** 받을 주소 미등록/등록/수정, 상세 `mailbox` 노출 조건, 기존 선물 상세 권한 정책이 통과한다. +### P11-T2 선물 상세 받을 주소 노출 조건 확장 — 2026-10-02 + +- 상태: 완료 +- 무엇을: 보낸 선물 상세의 `mailbox` 노출 조건을 `RECEIVED` 단일 상태에서 정상 진행 상태 중 `DELIVERED` 전(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)으로 확장했다. +- 왜: 팬이 운송장을 등록한 뒤에도 전달 완료 전까지 관리자 전역 선물 받을 주소를 상세에서 확인할 수 있어야 하기 때문이다. +- 어떻게: + - RED 확인: `GiftQueryServiceTest`, `GiftControllerTest`에 정상 진행 상태/종료 상태/받은 선물 방향 검증을 추가하고 기존 구현에서 focused test 실패를 확인했다. + - GREEN 구현: `GiftQueryService.mailboxFor` 조건을 `direction=SENT`이고 종료 상태가 아닌 경우로 단순화했다. + - 검증: `./gradlew test --tests '*GiftQueryServiceTest' --tests '*GiftControllerTest'`, `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.gift.*' --tests 'kr.co.vividnext.sodalive.v2.api.gift.*'`, `./gradlew ktlintCheck`, `git diff --check` 실행 결과 통과. +- 남은 항목: 없음 + ## Decision Log | 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 | diff --git a/docs/20260929_크리에이터_선물하기/prd.md b/docs/20260929_크리에이터_선물하기/prd.md index 500753bf..624672ce 100644 --- a/docs/20260929_크리에이터_선물하기/prd.md +++ b/docs/20260929_크리에이터_선물하기/prd.md @@ -186,6 +186,7 @@ INSPECTION_COMPLETED -> UNDELIVERABLE - 로그인 회원이 받는 크리에이터이면 보내는 팬의 닉네임만 알 수 있고, 팬이 신청 시 등록한 이름/휴대폰 번호/주소는 알 수 없다. - 로그인 회원이 보내는 팬이면 받는 크리에이터의 닉네임만 알 수 있고, 크리에이터가 입력한 이름/휴대폰 번호/주소는 알 수 없다. - 보내는 팬 상세에는 팬 본인이 신청 시 등록한 이름, 휴대폰 번호, 주소를 내려준다. +- 보내는 팬 상세에는 관리자가 등록한 전역 선물 받을 주소를 `mailbox`로 내려준다. 단, 정상 진행 상태 중 `DELIVERED` 전 상태(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)에서만 내려준다. - 받는 크리에이터 상세에는 크리에이터 본인이 입력한 받는 주소의 이름, 휴대폰 번호, 주소를 내려준다. - 주소 형식은 `(우편번호) 주소, 상세주소` 문자열로 내려준다. - 로그인 회원이 알아야 하는 데이터가 아니거나 아직 입력되지 않은 데이터는 `null`로 내려준다. @@ -446,7 +447,7 @@ Response: } ``` -`mailbox`는 관리자가 등록한 전역 단일 받을 주소다. 보낸 사람 관점(`direction=SENT`)이고 상태가 운송장 등록 전인 `RECEIVED`일 때만 내려준다. 받을 주소가 등록되지 않았거나 다른 상태/방향이면 `mailbox`는 `null`이다. 주소는 상세 조회 시점의 최신 관리자 설정을 사용한다. +`mailbox`는 관리자가 등록한 전역 단일 받을 주소다. 보낸 사람 관점(`direction=SENT`)이고 정상 진행 상태 중 `DELIVERED` 전 상태(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)일 때 내려준다. 받을 주소가 등록되지 않았거나, 다른 방향이거나, `DELIVERED`/`UNDELIVERABLE`/`CANCELED` 상태이면 `mailbox`는 `null`이다. 주소는 상세 조회 시점의 최신 관리자 설정을 사용한다. 받는 크리에이터 관점 응답 예시는 다음과 같다. @@ -516,7 +517,7 @@ Response: `direction=SENT`이면 보내는 팬 관점의 상세 응답이다. `giftInfo.recipientCreatorNickname`에는 받는 크리에이터 닉네임을 내려주고, `giftInfo.senderNickname`, `giftInfo.shippingRequestedAt`, `recipientAddress`는 `null`이다. `senderInfo`에는 팬 본인이 신청 시 등록한 이름, 휴대폰 번호, 주소를 내려준다. -`mailbox`는 코드상에서 정한 사서함 이름, 주소, 연락처를 내려준다. 구현 후 값이 제공되면 이 문서를 갱신한다. +`mailbox`는 관리자가 등록한 전역 단일 받을 주소의 이름, 주소, 연락처를 내려준다. 보낸 사람 관점의 정상 진행 상태 중 `DELIVERED` 전 상태에서만 값이 있고, 그 외에는 `null`이다. `direction=SENT`이고 현재 상태가 `RECEIVED`이면 `trackingRequired=true`이며, 팬 클라이언트는 운송장 등록 CTA를 표시한다. `direction=RECEIVED`이면 받는 크리에이터 관점의 상세 응답이다. `giftInfo.senderNickname`에는 발송인인 팬 닉네임을 내려주고, `giftInfo.recipientCreatorNickname`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`, `senderInfo`, `mailbox`는 `null`이다. @@ -806,7 +807,7 @@ Response: #### 8.13.3 관리자 선물 받을 주소 설정 API -선물 받을 주소는 전역 단일 설정이다. 팬이 운송장을 등록하기 전에 보낸 선물 상세에서 이 주소를 확인하고 택배를 발송한다. +선물 받을 주소는 전역 단일 설정이다. 팬은 정상 진행 상태 중 `DELIVERED` 전인 보낸 선물 상세에서 이 주소를 확인할 수 있다. `GET /api/v2/admin/gift-mailbox`