docs(gift): 사서함 노출 조건 문서를 갱신한다

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?,

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/문서 |

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`