docs(gift): 선물 받을 주소 요구사항을 기록한다

2026-10-01 22:58:41 +09:00
parent 322b07d794
commit 3fb822a096
3 changed files with 172 additions and 15 deletions
@@ -1309,6 +1309,48 @@ P7은 FCM 확장 후 전체 상태 전이를 연결하고 최종 회귀로 종
  - Gate 확인: Phase 9 focused suite, `./gradlew ktlintCheck`, `git diff --check` 모두 성공
 - 남은 항목: 없음

+## Phase 11: 선물 받을 주소 설정
+
+**Phase 결과:** 관리자는 전역 단일 선물 받을 주소를 등록/수정하고, 팬은 운송장 등록 전 상세에서 해당 주소를 확인할 수 있다.
+
+**선행조건:** `P3-GATE`, `P10-GATE` 완료.
+
+### 구현 항목
+
+#### Task 11.1 받을 주소 관리자 설정 API 구현
+
+**Goal 실행 `P11-T1`:** 전역 단일 받을 주소 조회/저장 API를 구현한다.
+
+- **Files:** Create `GiftMailbox.kt`, `GiftMailboxRepository.kt`; Modify `GiftAdminService.kt`, `AdminGiftController.kt`, `AdminGiftRequest.kt`, `AdminGiftResponse.kt`, `gift-schema.sql`; Test `GiftAdminServiceTest.kt`, `AdminGiftControllerTest.kt`.
+- [x] **RED:** 설정 미등록 시 `GET /api/v2/admin/gift-mailbox`가 `data=null`을 반환하는 실패 test를 작성한다.
+- [x] **RED:** `PUT /api/v2/admin/gift-mailbox`가 전역 단일 주소를 생성하고, 재호출 시 같은 row를 갱신하는 실패 test를 작성한다.
+- [x] **RED:** 이름/연락처/우편번호/주소 공백 입력을 거부하는 실패 test를 작성한다.
+- [x] **RED 확인:** focused test 실패를 확인한다.
+- [x] **GREEN:** 단일 row persistence, 관리자 service, request/response DTO, controller endpoint를 구현한다.
+- [x] **GREEN 확인:** focused test 통과를 확인한다.
+
+#### Task 11.2 선물 상세 받을 주소 노출 구현
+
+**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 확인:** focused test 실패를 확인한다.
+- [x] **GREEN:** `GiftQueryService`에서 받을 주소 repository를 조회해 기존 `GiftMailboxResult`로 매핑한다.
+- [x] **GREEN 확인:** focused test 통과를 확인한다.
+
+### Phase 11 Gate
+
+**Goal 실행 `P11-GATE`:** 관리자 설정과 사용자 상세 노출을 판정한다.
+
+```bash
+./gradlew test --tests "*GiftAdminServiceTest" --tests "*AdminGiftControllerTest" --tests "*GiftQueryServiceTest" --tests "*GiftControllerTest"
+./gradlew ktlintCheck
+```
+
+**Expected:** 받을 주소 미등록/등록/수정, 상세 `mailbox` 노출 조건, 기존 선물 상세 권한 정책이 통과한다.
+
 ## Decision Log

 | 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |