Files
sodalive-android/docs/20261002_선물_상세와_운송장_등록/prd.md
T

563 lines
49 KiB
Markdown

# PRD: 선물 상세와 운송장 등록
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 기존 Phase 1~7 완료, Phase 8 선물 UI 회귀 수정 기준 확정 |
| 작성일 | `2026-10-02` |
| 최종 수정일 | `2026-10-06` |
| 대상 제품 | Android 선물 상세·운송장 등록·신청 취소·받은 선물 배송지 입력 |
| 작성자·결정권자 | 사용자 요청 및 인터뷰 기준 |
| 관련 API Contract | 이 문서 11장 |
| 관련 구현 계획 | `docs/20261002_선물_상세와_운송장_등록/plan-task.md` |
| 선행 구현 | `docs/20261001_선물함_리스트_페이지/` |
| 관련 review | [Phase 3 운송장 화면](reviews/phase3-tracking-screen-review.md), [Phase 4 취소 ViewModel](reviews/phase4-cancel-viewmodel-review.md), [Phase 4 취소 화면](reviews/phase4-cancel-screen-review.md), [Phase 5 최종 회귀](reviews/phase5-final-regression-review.md) |
## 1. Overview
로그인 사용자가 선물함 카드에서 신청번호로 상세 화면에 진입해 선물의 현재 상태와 허용된 정보를 확인할 수 있게 한다. 보낸 선물 중 운송장 등록이 필요한 신청은 SODALIVE 사서함 주소를 확인하고 택배사와 운송장 번호를 등록할 수 있으며, 접수 상태의 보낸 신청은 확인 다이얼로그를 거쳐 취소할 수 있다.
Figma의 화면 구조와 문구를 따르되 상태와 데이터 노출은 API 계약을 우선한다. 정상 진행 API 상태 5개는 보존하고, 화면에는 Figma처럼 `신청 접수`, `발송 확인`, `사서함 도착`, `전달 완료` 4개 진행 구간으로 표시한다. `INSPECTION_COMPLETED`는 별도 진행 구간을 추가하지 않고 `사서함 도착` 구간의 완료 상태와 선물 정보의 `검수일`에 반영한다.
Phase 7에서는 받는 크리에이터 관점(`direction=RECEIVED`)의 상세와 배송지 입력을 추가한다. 선물함 리스트 item은 기존처럼 `applicationNo`만 상세에 전달하고, 상세 API 응답이 `direction=RECEIVED`일 때만 받은 선물 전용 상태와 배송지 입력 UI를 렌더링한다. 보낸 선물 상세, 운송장 등록, 신청 취소의 완료 이력과 검증 기록은 보존한다.
## 2. Problem Statement
아래는 최초 요구사항 수집 당시의 문제다. 이후 구현·검증 결과는 14장과 관련 리뷰에서 추적한다.
- 현재 선물함 카드는 상세 화면 대신 상태 toast만 표시한다.
- 사용자는 신청 이후 운송장 등록, 정상 진행 이력 확인, 전달 불가 사유 확인, 신청 취소를 완료할 화면이 없다.
- 보낸 사람과 받는 사람의 주소 데이터는 의미가 다르므로 상대방 개인정보를 노출하지 않는 방향별 표시 정책이 필요하다.
- 기존 `V2ModalDialog`는 확인 탭 즉시 닫혀 취소 API 실패 시 다이얼로그를 유지할 수 없다.
문제를 해결했다는 판단은 선물함에서 `applicationNo`로 상세를 열고, 상세 조회·운송장 등록·취소 API와 화면 상태가 계약대로 연결되며, 방향별 개인정보 노출과 5개 API 상태의 4구간 진행 표시가 local unit test로 검증되는 것으로 한다.
## 3. Goals
### 3.1 제품 목표
- 선물함 카드에서 `applicationNo`로 선물 상세를 연다.
- 상세 화면은 `GET /api/v2/gifts/{applicationNo}`의 `response.data`를 렌더링한다.
- 정상 진행 5개 API 상태와 상태별 안내·섹션·action을 정확히 표시한다.
- `trackingRequired=true`인 보낸 선물에서 운송장 정보를 한 번 등록한다.
- `direction=SENT && status=RECEIVED` 신청을 확인 다이얼로그 후 취소한다.
- 취소 API 성공 또는 상세 조회의 `status=CANCELED`에서 취소 완료 화면을 표시한다.
- `direction=RECEIVED && recipientAddressRequired=true`이면 받는 크리에이터가 배송지를 입력하고 약관 2개에 동의한 뒤 제출할 수 있다.
- 배송지 입력 성공 후 상세를 다시 조회해 배송지 입력 완료, 전달 완료, 전달 불가 상태를 API 계약대로 표시한다.
- 받은 선물 상세에서는 `senderInfo`, `mailbox`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`을 표시하지 않는다.
### 3.2 UX 목표
- 상단 고정 내비게이션과 하단 safe area는 기존 Android 패턴을 따른다.
- loading·content·error·retry·submit 상태에서 사용자가 현재 동작을 이해할 수 있게 한다.
- mutation 중 중복 탭을 막고 실패 시 입력 또는 취소 확인 문맥을 유지한다.
- Figma의 레이아웃·문구를 우선하되 API 상태·데이터 계약과 충돌하면 API를 우선한다.
## 4. Non-Goals
- iOS 구현 또는 iOS 문서.
- 운송장 등록 완료 후 수정 기능.
- 받은 선물 배송지 수정 기능. 배송지 최초 입력은 Phase 7 범위에 포함한다.
- 택배사 목록 API 조회.
- 신규 디자인 시스템, 신규 공통 dialog 또는 전역 event bus.
- 상대방의 `recipientAddress` 노출.
- 존재하지 않는 선물 리뷰 작성 또는 선물 정책 route 신규 구현.
- 선물 전용 이용약관·개인정보 화면 신규 구현. 이번 범위는 지정된 Notion URL 외부 브라우저 이동만 포함한다.
- iOS 구현 또는 iOS 문서. Android 외 플랫폼 고려사항은 이번 문서 범위에서 제외한다.
- `app/src/androidTest`, 기기·에뮬레이터 조작, 스크린샷·시각 QA.
## 5. Target Users and Permissions
| 사용자 | 목표 | 허용 정보·작업 |
|---|---|---|
| 보낸 팬 (`SENT`) | 신청 상태 확인, 운송장 등록, 접수 상태 신청 취소 | 크리에이터 닉네임, 본인의 `senderInfo`, SODALIVE `mailbox`; 상대방 `recipientAddress` 비노출 |
| 받는 크리에이터 (`RECEIVED`) | 수령 예정 선물 상태와 본인 배송지 확인 | 보낸 팬 닉네임, 본인이 입력한 `recipientAddress` |
- 인증은 기존 `SharedPreferenceManager.token`의 Bearer header 패턴을 재사용한다.
- 서버는 로그인 사용자가 접근 가능한 신청만 반환한다.
- `applicationNo`가 blank이면 API를 호출하지 않고 기존 오류 feedback 후 안전하게 종료한다.
## 6. 핵심 사용자 흐름
### 6.1 상세 조회
1. 사용자가 선물함 카드 또는 배송지 안내 배너를 누른다.
2. 앱은 카드의 `applicationNo`만 상세 Activity에 전달한다.
3. 상세 화면은 `GET /api/v2/gifts/{applicationNo}`를 호출한다.
4. 성공하면 상태·방향·nullable 데이터에 맞는 상태 안내, 4구간 progress, action, 정보 섹션을 표시한다.
5. `status=CANCELED`이면 일반 상세 대신 취소 완료 화면을 표시한다.
6. 실패하면 기존 오류 표시와 같은 신청번호 재시도를 제공한다.
### 6.2 운송장 등록
1. `trackingRequired=true`인 상세에서 `운송장 작성하기`를 누른다.
2. 운송장 등록 화면은 같은 상세 API를 다시 조회한다.
3. `trackingRequired=false`이면 오류를 표시하고 상세로 돌아간다.
4. `mailbox=null`이면 `받을 주소가 등록되어 있지 않습니다.`를 표시하고 등록을 막는다.
5. 사용자는 로컬 택배사 목록에서 한글 표시명을 선택하고 운송장 번호를 입력한다.
6. 유효한 입력에서 `POST /api/v2/gifts/{applicationNo}/tracking`을 한 번 호출한다.
7. 성공 toast 후 상세를 다시 열어 상세 API를 재조회하고 `TRACKING_REGISTERED`를 표시한다.
### 6.3 신청 취소
1. `direction=SENT && status=RECEIVED`에서 `신청 취소`를 누른다.
2. API를 호출하지 않고 `V2ModalDialog`를 먼저 표시한다.
3. `나가기`는 dialog만 닫고 현재 화면 상태를 유지한다.
4. `취소하기`는 중복 탭을 막고 `POST /api/v2/gifts/{applicationNo}/cancel`을 호출한다.
5. 실패하면 dialog를 유지하고 기존 오류 feedback을 표시해 재시도할 수 있게 한다.
6. 성공하면 dialog를 닫고 취소 응답을 반영한 취소 완료 상태로 replace한다.
7. 뒤로가기는 취소 전 상세·운송장 화면이 아니라 선물함으로 이동한다.
### 6.4 받은 선물 배송지 입력과 상세 상태
1. 사용자가 선물함 리스트의 받은 선물 item 또는 배송지 입력 안내 배너를 누른다.
2. 앱은 item의 `applicationNo`만 `GiftDetailActivity`에 전달한다.
3. 상세 화면은 `GET /api/v2/gifts/{applicationNo}`를 호출하고 `response.data`를 사용한다.
4. `direction=SENT`이면 기존 보낸 선물 상세 정책을 유지하고 받은 선물 전용 UI를 렌더링하지 않는다.
5. `direction=RECEIVED && recipientAddressRequired=true`이면 Figma `2531:36290` 기준의 `선물 받기` 화면과 배송지 입력 form을 표시한다.
6. 이름, 휴대폰 번호, 우편번호, 주소, 약관 2개가 유효할 때만 `선물 받기` CTA를 활성화한다. 상세 주소는 선택 입력이다.
7. 우편번호 검색은 기존 `KakaoPostcodeSearchActivity`의 embed 기반 Kakao 우편번호 서비스를 재사용하고 선택 결과는 우편번호·주소만 채운다.
8. CTA 탭 시 `POST /api/v2/gifts/{applicationNo}/recipient-address`를 호출한다. submit 중 중복 탭은 막고 실패 시 입력값과 약관 체크 상태를 유지한다.
9. 성공하면 기존 toast 패턴으로 성공 feedback을 표시하고 같은 상세를 다시 조회한다.
10. 재조회 결과가 배송지 입력 완료, 전달 완료, 전달 불가 중 하나이면 각 Figma 상태 UI를 표시한다.
## 7. 정보 구조와 라우팅
```text
GiftInboxActivity
-> GiftDetailActivity(applicationNo)
-> GiftTrackingActivity(applicationNo)
-> V2ModalDialog -> cancel API
-> Canceled completion state
-> Kakao inquiry
```
- `GiftDetailActivity.newIntent(context, applicationNo)`와 `GiftTrackingActivity.newIntent(context, applicationNo)`를 제공한다.
- DTO 전체나 주소 데이터는 Intent로 전달하지 않는다.
- 취소 완료 전용 Activity는 만들지 않고 `GiftDetailActivity`의 취소 완료 상태로 렌더링한다.
- 운송장 등록 성공은 상세를 재조회하도록 결과를 반환하거나 기존 상세를 제거하는 replace navigation을 사용한다.
- 취소 성공은 취소 전 상세·등록 화면이 back stack에 남지 않도록 선물함으로 안전하게 돌아가는 경로를 보장한다.
- 상세에서 변경이 발생한 뒤 선물함으로 돌아오면 기존 `GiftInboxViewModel.refresh()`를 사용해 목록을 갱신한다.
- mutation 성공 후 상세 Activity가 재생성되어도 변경 여부 Boolean을 저장·복원해 `RESULT_OK`를 유지한다. 변경 없는 일반 상세와 mutation 없는 `CANCELED` 조회는 재생성 후에도 성공 결과를 만들지 않는다.
## 8. 기능 요구사항
### 8.1 상세 진입과 조회
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-DETAIL-001` | 확정 | 목록 카드 탭은 상태 toast 대신 `applicationNo` 상세 이동 event를 발생시킨다. | event가 한 번 소비되고 Intent에 같은 신청번호가 담긴다. | `P2-T3` |
| `GIFT-DETAIL-002` | 확정 | 상세는 진입 시 상세 API를 호출하고 `response.data`를 사용한다. | loading/content/error/retry와 null payload 오류가 검증된다. | `P1-T1`, `P1-T2`, `P2-T2` |
| `GIFT-DETAIL-003` | 확정 | `status=CANCELED`는 일반 상세가 아닌 취소 완료 상태로 렌더링한다. | 직접 진입과 취소 성공 경로가 같은 완료 모델을 사용한다. | `P2-T1`, `P2-T2`, `P4-T3` |
### 8.2 hero와 진행 상태
| status | chip | title | body |
|---|---|---|---|
| `RECEIVED` | 없음 또는 `접수 완료` | `선물 신청 완료!` | `선물이 정상적으로 접수되었어요!` |
| `TRACKING_REGISTERED` | `발송 확인` | `사서함으로 이동 중이에요` | 없음 |
| `ARRIVED_AT_MAILBOX` | `사서함 도착` | `선물이 사서함에 도착했어요` | 없음 |
| `INSPECTION_COMPLETED` | `검수 완료` | `선물 검수를 완료했어요` | 없음 |
| `DELIVERED` | `전달 완료` | `크리에이터에게 선물을 전달했어요` | 없음 |
| `UNDELIVERABLE` | `전달 불가` | `전달할 수 없는 품목입니다` | `보내주신 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.` |
| `CANCELED` | `취소 완료` | `선물 신청이 취소되었어요` | `{크리에이터}에게 보내는 선물 신청({신청번호})이 취소되었습니다. 취소한 신청은 되돌릴 수 없으며, 다시 보내려면 새로 신청해 주세요.` |
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-STATUS-001` | 확정 | `RECEIVED`는 `선물 신청 완료!`/`선물이 정상적으로 접수되었어요!`를 표시한다. | chip은 없거나 `접수 완료`다. | `P2-T1` |
| `GIFT-STATUS-002` | 확정 | `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`, `DELIVERED`는 명세의 chip/title을 표시한다. | 각 status가 지정 문구에 매핑된다. | `P2-T1` |
| `GIFT-STATUS-003` | 확정 | `UNDELIVERABLE`과 `CANCELED`는 명세의 종료 상태 안내를 표시한다. | 종료 상태가 정상 progress step으로 추가되지 않는다. | `P2-T1`, `P4-T3` |
| `GIFT-STATUS-004` | 확정 | `RECEIVED`, `CANCELED`, `UNDELIVERABLE`은 공통 hero illustration과 progress를 표시하지 않고 Figma의 좌측 정렬 상태 안내 섹션만 표시한다. | 선물 아이콘·중앙 정렬 hero·progress가 숨겨지고 상태별 tag/title/body만 지정 위치에 표시된다. | `P6-T1` |
| `GIFT-TIMELINE-001` | 정정 | API의 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`, `DELIVERED` 상태를 보존하되 화면 progress는 Figma의 4개 가로 구간으로 표시한다. | `INSPECTION_COMPLETED`는 `사서함 도착` 구간 완료와 `검수일`에 반영되고 별도 다섯 번째 구간을 만들지 않는다. | `P6-T1` |
| `GIFT-TIMELINE-002` | 확정 | `occurredAt`이 있으면 완료 색상과 `MM.dd`, null이면 비활성 색상과 날짜 미표시다. | 순수 formatter/presenter test가 완료·미완료를 검증한다. | `P2-T1` |
| `GIFT-TIMELINE-003` | 확정 | 종료 상태에서도 `statusTimeline`의 정상 진행 이력을 유지한다. | `UNDELIVERABLE`, `CANCELED` fixture가 이력 손실 없이 매핑된다. | `P2-T1` |
### 8.3 정보 섹션과 개인정보
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-INFO-001` | 확정 | 선물 정보는 항상 표시하며 direction별 상대 닉네임과 nullable 필드를 계약대로 표시한다. | paidCan, tracking, 검수일, 전달 완료일, 취소일의 조건부 표시가 검증된다. | `P2-T1` |
| `GIFT-PRIVACY-001` | 확정 | `direction=SENT`는 `recipientAddress`를 절대 노출하지 않는다. | 응답에 값이 있어도 presentation model에 포함되지 않는다. | `P2-T1` |
| `GIFT-PRIVACY-002` | 확정 | `direction=RECEIVED`는 본인이 입력한 `recipientAddress.name/phoneNumber/address`만 배송지로 표시할 수 있다. | nullable이면 섹션을 숨긴다. | `P2-T1` |
| `GIFT-MAILBOX-001` | 확정 | `mailbox`는 관리자 등록 SODALIVE 전역 사서함이며 SENT 상세와 운송장 등록의 보낼 주소로 사용한다. | `recipientAddress`와 대체·혼합하지 않는다. | `P2-T1`, `P3-T1` |
| `GIFT-SENDER-001` | 확정 | `senderInfo`가 있으면 본인이 신청 시 입력한 이름·전화번호·주소를 표시한다. | null이면 섹션을 숨긴다. | `P2-T1` |
| `GIFT-UNDELIVERABLE-001` | 확정 | 전달 불가 사유 제목은 reason 또는 `전달 불가`, 안내는 폐기·미반송 문구를 사용한다. | null reason fallback과 지정 안내가 검증된다. | `P2-T1` |
### 8.4 action
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-ACTION-001` | 확정 | `trackingRequired=true`이면 `운송장 작성하기`를 표시한다. | false에서는 route 직접 진입도 제출할 수 없다. | `P2-T1`, `P2-T2`, `P3-T1`, `P3-T2` |
| `GIFT-ACTION-002` | 확정 | `direction=SENT && status=RECEIVED`이면 `신청 취소`를 표시한다. | 다른 조합에서는 취소 API를 호출할 수 없다. | `P2-T1`, `P4-T2`, `P4-T3` |
| `GIFT-ACTION-003` | 확정 | 문의하기는 기존 카카오 문의 route를 재사용한다. | 기존 URL의 ACTION_VIEW intent를 사용한다. | `P2-T2` |
| `GIFT-ACTION-004` | 제외 | gift 전용 리뷰 작성 및 선물 정책 route가 없으므로 두 action은 숨긴다. | 신규 route를 만들지 않는다. | `P2-T2` |
### 8.5 운송장 등록
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-TRACKING-001` | 확정 | 등록 화면은 상세 API를 재조회해 신청 요약과 `mailbox`를 표시한다. | 신청일은 RECEIVED 이력의 `YYYY.MM.dd`다. | `P3-T1`, `P3-T2` |
| `GIFT-TRACKING-002` | 확정 | 택배사는 앱 로컬 상수 14개를 사용하고 한글 표시명을 그대로 전송한다. | 택배사 API 호출이 없고 request body가 선택한 표시명과 일치한다. | `P3-T1` |
| `GIFT-TRACKING-003` | 정정 | 택배사 선택과 ASCII 숫자 10~14자리 운송장 번호가 있어야 CTA가 활성화된다. | 9자리 이하·15자리 이상·비숫자·택배사 미선택 입력은 API를 호출하지 않는다. 15번째 문자는 입력 단계에서 차단한다. | `P6-T2` |
| `GIFT-TRACKING-005` | 확정 | 운송장 입력은 숫자 키패드를 요청하고 ASCII 숫자만 허용하며 14자로 제한한다. | 1~9자리 입력에는 `올바른 운송장 번호를 입력해 주세요`와 accent border를 표시하고 빈 입력은 오류를 숨긴다. | `P6-T2` |
| `GIFT-TRACKING-004` | 확정 | submit 중 중복 요청을 막고 성공 후 상세를 재조회한다. | 성공 event는 한 번 소비되고 `TRACKING_REGISTERED` 상세가 표시된다. | `P3-T2`, `P3-T3` |
택배사 로컬 상수:
```text
CJ대한통운, 우체국택배, GS25 편의점택배, CU 편의점택배,
한진택배, 롯데택배, 로젠택배, 경동택배, 대신택배, 일양로지스,
천일택배, 합동택배, 건영택배, 농협택배
```
### 8.6 신청 취소와 V2 dialog
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-CANCEL-001` | 확정 | 취소 버튼은 API 전에 `V2ModalDialog`를 표시한다. | dialog 표시만으로 API 호출이 발생하지 않는다. | `P4-T1`, `P4-T2`, `P4-T3` |
| `GIFT-CANCEL-002` | 확정 | `V2ModalDialog`는 기존 호출 호환성을 유지하며 opt-in 비자동 닫힘과 명시적 dismiss를 지원한다. | 기본 호출은 기존처럼 닫히고 opt-in 확인은 API 결과 전까지 유지된다. | `P4-T1` |
| `GIFT-CANCEL-003` | 확정 | 취소 실패는 dialog와 상세 상태를 유지하고 재시도를 허용한다. | 실패 후 confirm을 다시 누를 수 있고 in-flight 중에는 중복 호출이 없다. | `P4-T2`, `P4-T3` |
| `GIFT-CANCEL-004` | 확정 | 취소 성공은 `canceledAt`, `priceCan`을 우선 사용해 취소 완료 상태를 표시한다. | 상세 재조회 시에는 delivery/giftInfo fallback을 사용한다. | `P2-T1`, `P4-T2`, `P4-T3` |
### 8.7 받은 선물 상세 분기와 개인정보
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-RECEIVED-001` | 확정 | 선물함 리스트 item 탭은 `applicationNo`만 상세로 전달한다. | DTO·주소·전화번호를 Intent extra로 전달하지 않는다. | `P7-T5` |
| `GIFT-RECEIVED-002` | 확정 | 상세 진입 시 `GET /api/v2/gifts/{applicationNo}`를 호출하고 `response.data`로 렌더링한다. | `response.success && data != null`만 content로 처리한다. | `P7-T2`, `P7-T3` |
| `GIFT-RECEIVED-003` | 확정 | `direction=RECEIVED`가 아니면 받은 선물 전용 화면을 렌더링하지 않는다. | `SENT`는 기존 보낸 선물 상세로 유지되고, 잘못된 접근은 기존 오류/재라우팅 정책을 따른다. | `P7-T3` |
| `GIFT-RECEIVED-004` | 확정 | RECEIVED 화면에서 `senderInfo`, `mailbox`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`은 표시하지 않는다. | presenter/UI model에 받은 선물 노출 금지 필드가 포함되지 않는다. | `P7-T2` |
| `GIFT-RECEIVED-005` | 확정 | `recipientAddress=null`이면 받는 주소 섹션 전체를 숨긴다. | 빈 섹션, skeleton, `-` 값이 없다. | `P7-T2`, `P7-T4` |
### 8.8 배송지 입력 전 UI와 제출
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-ADDRESS-FORM-001` | 확정 | `direction=RECEIVED && recipientAddressRequired=true`이면 Figma `2531:36290`의 `선물 받기` 화면을 표시한다. | 개인정보 이용 안내, 전달 예정 선물, 배송지 입력, 이용 약관 동의, 하단 CTA가 있다. | `P7-T2`, `P7-T4` |
| `GIFT-ADDRESS-FORM-002` | 확정 | 전달 예정 선물 섹션은 `giftInfo.senderNickname`, `sizeName`, `categoryName`만 표시한다. | 금지 필드는 표시하지 않는다. | `P7-T2` |
| `GIFT-ADDRESS-FORM-003` | 확정 | 이름, 휴대폰 번호, 우편번호, 주소가 공백이 아니고 약관 2개가 모두 체크되어야 제출 가능하다. | 상세 주소는 선택 입력이고 누락돼도 CTA 활성 조건을 막지 않는다. | `P7-T1`, `P7-T3` |
| `GIFT-ADDRESS-FORM-004` | 확정 | `POST /api/v2/gifts/{applicationNo}/recipient-address`는 화면 입력값과 약관 boolean을 그대로 전송한다. | request body key가 API 명세와 일치하고 submit 중 중복 POST가 없다. | `P7-T1`, `P7-T3` |
| `GIFT-ADDRESS-FORM-005` | 확정 | 성공 시 성공 toast를 표시하고 상세를 다시 조회한다. | 재조회 후 `recipientAddressRequired=false` 상태 UI가 표시된다. | `P7-T3`, `P7-T5` |
| `GIFT-ADDRESS-FORM-006` | 확정 | 실패 시 기존 form error/toast/dialog 패턴을 따르고 입력값을 유지한다. | 실패 뒤 이름·전화번호·주소·약관 체크가 초기화되지 않는다. | `P7-T3`, `P7-T4` |
| `GIFT-ADDRESS-FORM-007` | 확정 | 약관 상세 링크는 기존 약관/webview 경로가 있을 때만 연결한다. | 기존 경로가 없으면 새 페이지를 만들지 않는다. | `P7-T4` |
### 8.9 Kakao 우편번호 검색
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-POSTCODE-001` | 확정 | 기존 `KakaoPostcodeSearchActivity`를 재사용한다. | 공식 script `https://t1.kakaocdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js`와 `embed()` 기반 구현을 유지한다. | `P7-T4` |
| `GIFT-POSTCODE-002` | 확정 | 선택 결과의 `zonecode`는 `recipientZipCode`, 도로명/지번 주소는 `recipientAddress`에 넣는다. | `userSelectedType == "R"`이면 `roadAddress`, 아니면 `jibunAddress`를 사용한다. | `P7-T4` |
| `GIFT-POSTCODE-003` | 확정 | 상세 주소는 Kakao 결과로 채우지 않고 사용자가 직접 입력한다. | 주소 선택 후 상세 주소 입력으로 focus를 이동한다. | `P7-T4` |
| `GIFT-POSTCODE-004` | 확정 | 주소 검색 실패·취소는 기존 form 값을 초기화하지 않는다. | 이름, 전화번호, 약관 체크, 기존 입력 주소 상태가 유지된다. | `P7-T3`, `P7-T4` |
### 8.10 받은 선물 상태별 완료 UI
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-RECEIVED-COMPLETE-001` | 확정 | `recipientAddressRequired=false`이고 status가 `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED` 중 하나이며 `recipientAddress`가 있으면 Figma `2531:36399`를 표시한다. | title `선물 상세`, hero `배송지 입력 완료!`, 문의하기, 선물 정보, 받는 주소가 표시된다. | `P7-T2`, `P7-T4` |
| `GIFT-RECEIVED-COMPLETE-002` | 확정 | `status=DELIVERED`이면 Figma `2531:36330`의 전달 완료 UI를 표시한다. | hero `선물 전달 완료!`, 배송 완료일은 `statusTimeline`의 `DELIVERED.occurredAt`을 사용한다. | `P7-T2`, `P7-T4` |
| `GIFT-RECEIVED-COMPLETE-003` | 확정 | 전달 완료의 받는 주소 섹션은 주소가 있을 때만 표시하고 보조 문구 `배송 완료 3일 후 해당 정보는 사라져요`를 포함한다. | `recipientAddress=null`이면 섹션 전체를 숨긴다. | `P7-T2`, `P7-T4` |
| `GIFT-RECEIVED-UNDELIVERABLE-001` | 확정 | `status=UNDELIVERABLE`이면 Figma `2531:36422`의 전달 불가 UI를 표시하고 배송지 입력 UI를 표시하지 않는다. | chip/title/body, 문의하기, 선물 정책 확인, 사유 섹션이 표시된다. | `P7-T2`, `P7-T4` |
| `GIFT-RECEIVED-UNDELIVERABLE-002` | 확정 | 전달 불가 사유는 `delivery.undeliverableReason` 또는 `전달 불가`, 안내는 `해당 선물은 정책에 따라 폐기되며 반송되지 않습니다.`를 사용한다. | reason null fallback이 검증된다. | `P7-T2` |
| `GIFT-RECEIVED-UNDELIVERABLE-003` | 확정 | 전달 불가에서는 응답에 `recipientAddress`가 있어도 받는 주소 섹션을 표시하지 않는다. | Figma에 없는 주소 섹션이 없다. | `P7-T2`, `P7-T4` |
### 8.11 받은 선물 action과 날짜
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-RECEIVED-ACTION-001` | 확정 | 문의하기는 기존 카카오 채널 문의 연결과 동일하게 처리한다. | 기존 ACTION_VIEW URL을 재사용한다. | `P7-T3`, `P7-T4` |
| `GIFT-RECEIVED-ACTION-002` | 확정 | 선물 정책 확인은 action handler만 만들고 임의 URL을 연결하지 않는다. | no-op 금지 정책이 있으면 `준비 중입니다.` toast만 표시한다. | `P7-T3`, `P7-T4` |
| `GIFT-DATE-001` | 확정 | 선물 상세 페이지의 모든 상세 필드 날짜는 UTC ISO를 기기 timezone 기준 `yyyy.MM.dd`로 표시한다. | 보낸 것과 받은 것 모두 timezone 경계 test가 통과한다. | `P7-T1`, `P7-T2` |
| `GIFT-DATE-002` | 확정 | 날짜 값이 null이거나 파싱 실패하면 해당 row를 숨긴다. | 현재 날짜나 `-`로 대체하지 않는다. | `P7-T2` |
### 8.12 Phase 8 상태 배지·상단 이미지·약관 터치 회귀 수정
| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `GIFT-UI-DEBUG-001` | 확정 | 신청 상세 상단에 Figma에 없는 선물 이미지를 표시하지 않는다. | 모든 상세 상태에서 `hero_illustration`이 렌더링되지 않는다. | `P8-R1` |
| `GIFT-UI-DEBUG-002` | 확정 | 상태 배지는 Figma의 상태별 배경·전경 조합을 사용한다. | 일반 진행 상태는 흰 배경·검은 글자, `UNDELIVERABLE`은 빨간 배경·검은 글자, `CANCELED`는 회색 배경·흰 글자이며 chip이 없는 상태는 숨긴다. | `P8-R2` |
| `GIFT-UI-DEBUG-003` | 정정 | 받은 사람 배송지 입력의 이용약관과 개인정보 `(필수)` 터치 처리를 전용 함수로 분리한다. | 두 함수 모두 `ACTION_VIEW`로 `https://app.notion.com/p/3eb27b359673802b937ae741ab7b4ad3`을 열고 체크 상태·CTA 계산을 유지한다. | `P8-R3` |
## 9. UI/UX Expectations
### 9.1 Figma 기준
- 운송장 등록 전 상세: `2481:19011`
- 운송장 등록 후 상세: `2481:19152`
- 전달 완료 상세: `2481:19320`
- 전달 불가: `2481:19456`
- 취소 확인 dialog: `2481:19500`
- 취소 완료: `2481:19521`
- 운송장 등록 비활성: `2481:19066`
- 운송장 등록 활성: `2481:19109`
- 받은 선물 배송지 입력 전 상세: `2531:36290`
- 받은 선물 배송지 입력 완료 후 상세: `2531:36399`
- 받은 선물 전달 완료 상세: `2531:36330`
- 받은 선물 전달 불가 상세: `2531:36422`
### 9.2 화면 구조
- 신청 완료: 우측 닫기 navigation, 공통 hero illustration과 progress 없이 좌측 정렬 제목·설명, 보낼 주소, 등록 안내, 선물 정보와 신청 취소, 하단 `운송장 작성하기` action bar.
- 일반 상세: 고정 `신청 상세` header, 좌측 정렬 상태 tag/title, 4구간 가로 progress, 상태별 action, 행 단위 정보 카드와 구분선.
- 전달 불가: progress 없이 accent 상태 tag와 설명, 문의하기, 사유 카드, 선물 정보 순서로 표시한다. route가 없는 `선물 정책 확인`은 만들지 않는다.
- 취소 완료: 고정 `취소 완료` header, 공통 hero illustration과 progress 없이 gray 상태 tag·좌측 정렬 제목·동적 안내문, `크리에이터/선물 사이즈/카테고리/신청번호/신청일/취소일/환불 캔` 7행 카드, 전체 폭 문의하기.
- 운송장 등록: 고정 header, 신청 요약 카드, 보낼 주소, 운송장 정보, 등록 안내, 하단 `신청 취소`/`등록 완료` action bar.
- 받은 선물 배송지 입력 전: 고정 `선물 받기` header, 개인정보 이용 안내 배너, 전달 예정 선물 카드, 배송지 입력 form, 약관 2개, 하단 `선물 받기` action bar.
- 받은 선물 배송지 입력 완료: 고정 `선물 상세` header, `배송지 입력 완료!` hero, 문의하기, 선물 정보, 받는 주소 섹션. `recipientAddress=null`이면 받는 주소 섹션은 없다.
- 받은 선물 전달 완료: 고정 `선물 상세` header, `선물 전달 완료!` hero, 문의하기, 배송 완료일 포함 선물 정보, 주소가 있을 때만 받는 주소 섹션과 3일 후 삭제 안내.
- 받은 선물 전달 불가: 고정 `선물 상세` header, `전달 불가` chip, 문의하기·선물 정책 확인 action, 사유 카드만 표시한다. 배송지 입력과 받는 주소 섹션은 표시하지 않는다.
- 기존 color, typography, spacing, card, input, button resource를 우선 재사용한다.
- 택배사 선택은 기존 Android 선택 UI 중 가장 가까운 spinner/dialog 패턴을 재사용한다.
- 정보 카드는 단일 multiline 문자열이 아니라 Figma의 고정 label 폭과 개별 value를 가진 행 구조로 표시한다.
- Figma에만 있고 앱 route가 없는 리뷰·선물 정책 action은 이번 UI 재구현에서도 추가하지 않는다.
- 받은 선물 전달 불가의 `선물 정책 확인`은 요구사항상 버튼/action handler만 만들고 임의 URL을 연결하지 않는다. 기존 앱 정책상 무동작 handler가 금지되면 `준비 중입니다.` toast를 사용한다.
- 신청 상세 상단에는 선물 이미지를 표시하지 않는다.
- 상태 배지는 일반 진행·전달 불가·취소 완료를 서로 다른 배경·전경 조합으로 표시한다.
### 9.3 취소 dialog 문구
- 제목: `신청 취소`
- 본문 첫 줄: `{크리에이터}에게 보내는 선물을 취소할까요?`
- 본문 둘째 줄: `선물 보내기 규정에 따라 선물 취소 및 사용한 캔이 모두 환불됩니다.`
- 왼쪽: `나가기`
- 오른쪽: `취소하기`
## 10. 날짜 표시 정책
- 입력은 UTC ISO 문자열이다.
- 앱의 기존 날짜 formatter 패턴에 맞춰 기기 timezone으로 변환한다.
- progress: `MM.dd`.
- 정보 카드·신청 요약·취소 상세: `yyyy.MM.dd`.
- 받은 선물 상세의 배송 신청일·배송 완료일도 `yyyy.MM.dd`를 사용한다.
- null 또는 파싱 실패 날짜는 임의 날짜를 만들지 않고 해당 값 또는 행을 숨긴다.
- 기존 상세 formatter가 이미 기기 timezone으로 표시하는지 `TimeZone.setDefault` 기반 local unit test로 확인한다. 그렇지 않으면 formatter를 수정해 보낸 것과 받은 것 모두 같은 기기 timezone 기준을 사용한다.
## 11. API 계약
### 11.1 공통 규칙
- 모든 endpoint는 로그인 Bearer 인증을 사용한다.
- Retrofit 반환형은 기존 `Single<ApiResponse<T>>`를 사용한다.
- 성공 payload는 `response.data`다.
- `success=false`, `data=null`, transport 오류는 성공 화면으로 처리하지 않는다.
### 11.2 상세 조회
```http
GET /api/v2/gifts/{applicationNo}
```
`GiftDetailResponse` 필드:
| 필드 | 타입 |
|---|---|
| `applicationNo` | `String` |
| `direction` | `SENT` 또는 `RECEIVED` |
| `status`, `statusName` | `String` |
| `giftInfo` | `GiftDetailInfoResponse` |
| `senderInfo` | `GiftAddressResponse?` |
| `recipientAddress` | `GiftAddressResponse?` |
| `mailbox` | `GiftAddressResponse?` |
| `trackingRequired`, `recipientAddressRequired` | `Boolean` |
| `recipientAddressDeadlineAt` | `String?` |
| `delivery` | `GiftDeliveryResponse` |
| `statusTimeline` | `List<GiftStatusTimelineResponse>` |
중첩 DTO:
| DTO | 필드 |
|---|---|
| `GiftDetailInfoResponse` | `recipientCreatorNickname: String?`, `senderNickname: String?`, `sizeName: String`, `categoryName: String`, `applicationNo: String?`, `paidCan: Int?`, `tracking: String?`, `shippingRequestedAt: String?` |
| `GiftAddressResponse` | `name: String`, `phoneNumber: String`, `address: String` |
| `GiftDeliveryResponse` | `canceledAt: String?`, `undeliverableAt: String?`, `undeliverableReason: String?` |
| `GiftStatusTimelineResponse` | `status: String`, `statusName: String`, `occurredAt: String?` |
### 11.3 운송장 등록
```http
POST /api/v2/gifts/{applicationNo}/tracking
Content-Type: application/json
{
"courierCompanyName": "한진택배",
"trackingNumber": "123456789012"
}
```
- response data는 `applicationNo`, `status`, `statusName`, `courierCompanyName`, `trackingNumber`, `trackingRegisteredAt`, `recipientAddressDeadlineAt`을 사용한다.
### 11.4 신청 취소
```http
POST /api/v2/gifts/{applicationNo}/cancel
```
- request body는 없다.
- response data는 `applicationNo`, `status`, `statusName`, `priceCan`, `canceledAt`을 사용한다.
### 11.5 받은 선물 배송지 입력
```http
POST /api/v2/gifts/{applicationNo}/recipient-address
Content-Type: application/json
{
"recipientName": "크리에이터이름",
"recipientPhoneNumber": "01012345678",
"recipientZipCode": "04030",
"recipientAddress": "서울특별시 마포구 양화로 000",
"recipientAddressDetail": "3층",
"recipientTermsAgreed": true,
"recipientPrivacyAgreed": true
}
```
- response data는 `applicationNo`, `status`, `statusName`, `recipientAddressRegisteredAt`을 사용한다.
- 성공 후 화면은 이 응답만으로 최종 렌더링하지 않고 상세를 다시 조회한다.
## 12. 보안과 데이터 취급
- token, BuildConfig 값, 내부 URL, 전체 주소·전화번호를 log 또는 crash message에 기록하지 않는다.
- SENT 화면에는 응답에 값이 있어도 상대방 `recipientAddress`를 전달하거나 표시하지 않는다.
- Intent에는 `applicationNo`만 전달하고 주소·전화번호를 extra로 전달하지 않는다.
- fixture는 가상 이름·전화번호·주소를 사용한다.
- 승인된 Gift 전용 예외로 `AppDI.kt`의 named Gift client/Retrofit만 분리한다. Gift 로깅은 debug/release 모두 NONE이며 공유 client의 debug BODY/release NONE 정책과 다른 API 연결은 유지한다.
- 상세 Activity saved state에 새로 저장하는 값은 변경 여부 Boolean뿐이다. 주소·전화번호·DTO·취소 응답을 추가 저장하지 않는다.
## 13. 성능과 품질 요구사항
- 화면별 최초 조회와 mutation의 중복 요청을 막는다.
- 취소·등록 실패 시 사용자가 입력하거나 보고 있던 상태를 유지한다.
- local unit test는 presenter/formatter, repository 전달, ViewModel 상태, navigation event, modal 호환성을 검증한다.
- layout 크기·간격·constraint·visibility를 직접 검증하는 테스트는 작성하지 않는다.
- 공통 `V2ModalDialog` 수정으로 인해 기존 modal local unit test와 전체 local unit test를 최종 회귀로 실행한다.
## 14. 성공 기준
### 14.1 기능 (Phase 1~5 완료 이력)
- [x] 목록 item이 `applicationNo` 상세로 이동한다.
- [x] 상세 API의 `response.data`로 상태별 화면을 렌더링한다.
- [x] 정상 progress 5개가 순서대로 표시된다.
- [x] `trackingRequired=true`에서만 운송장 작성 흐름이 동작한다.
- [x] 취소 확인 전에는 취소 API를 호출하지 않는다.
- [x] 취소 실패 시 dialog가 유지되고 성공 시 취소 완료 상태로 전환된다.
- [x] 운송장 등록 성공 후 상세를 재조회한다.
### 14.2 개인정보·UI (Phase 1~5 완료 이력)
- [x] SENT에서 `recipientAddress`가 노출되지 않는다.
- [x] RECEIVED에서 본인의 `recipientAddress`만 조건부 표시된다.
- [x] `mailbox`는 SODALIVE 사서함으로만 표시된다.
- [x] Figma 구조와 문구를 source/resource 대조로 확인했으며 5단계·API 데이터 계약을 우선한다.
- [x] review/policy route를 새로 만들지 않는다.
- [x] Gift 요청·응답은 전용 NONE 로깅 경로를 사용하며 공유 네트워크 정책을 바꾸지 않는다.
Figma/layout 증거는 소스와 리소스 대조에 한정한다. 화면 표현 로직과 라우팅은 local unit test로 검증했으며 기기·에뮬레이터·androidTest·스크린샷·시각 QA는 제외했다. 위 체크는 실기기 렌더링이나 픽셀 일치 검증을 뜻하지 않는다.
### 14.3 품질 (Phase 1~5 완료 이력)
- [x] focused gift/modal local unit test가 통과한다.
- [x] 전체 local unit test, resource merge, Kotlin compile, ktlint가 통과한다.
- [x] 모든 확정 요구사항이 `plan-task.md`의 Task와 검증 증거에 연결된다.
- [x] mutation 성공 결과는 recreate 후 보존되고 변경 없는 일반 상세·CANCELED 조회는 성공 결과를 만들지 않는다.
### 14.4 Phase 6 Figma UI 재구현
- [x] 신청 완료·운송장 등록·등록 오류·등록 후 상세·전달 완료·전달 불가·취소 완료의 콘텐츠 계층이 대응 Figma 노드와 일치한다.
- [x] 정상 진행 API 상태 5개가 Figma의 4구간 progress에 손실 없이 매핑된다.
- [x] 신청 완료·전달 불가·취소 완료에는 공통 hero illustration과 progress가 표시되지 않는다.
- [x] 취소 완료가 동적 안내문과 7행 취소 상세 카드를 표시한다.
- [x] 운송장 번호는 ASCII 숫자 10~14자리만 유효하고 15번째 문자는 입력되지 않는다.
- [x] layout 속성을 직접 검증하는 테스트를 추가하지 않고 presenter/validation의 화면 결정 로직을 local unit test로 검증한다.
- [x] 관련 local unit, resource merge, Kotlin compile, ktlint와 debug assemble이 통과한다.
기존 14.1~14.3의 완료 체크는 Phase 1~5 당시 증거를 보존한다. Phase 6 항목이 완료되기 전에는 최신 Figma UI가 구현 완료됐다고 판정하지 않는다.
최종 근거는 `plan-task.md` 마지막 Verification Log와 Phase 6 리뷰의 2차 수정 검증 기록이다. P6-R3 이후 직렬 Gate는 gift/modal 149개, 전체 unit 1,416개, failures/errors/skipped=0이다. resource/compile/ktlint와 assembleDebug가 성공했고 diff check는 exit 0이었다. goal·QA·quality·직접 security·context review는 모두 PASS, `REV-P6-T1-001`과 `REV-P6-REVIEW-001`은 수정·검증 완료다.
### 14.5 Phase 7 받은 선물 상세·배송지 입력
- [x] 받은 선물 상세 진입 시 `GET /api/v2/gifts/{applicationNo}`를 호출하고 `direction=RECEIVED` 상태만 받은 선물 UI로 렌더링한다.
- [x] `recipientAddressRequired=true`이면 배송지 입력 form과 약관 2개, `선물 받기` CTA가 표시된다.
- [x] 필수 입력 또는 약관이 누락되면 배송지 POST를 호출하지 않는다.
- [x] 배송지 POST request body가 API 명세와 일치하고 submit 중 중복 요청이 없다.
- [x] 배송지 입력 성공 후 상세를 재조회하고 배송지 입력 완료 UI를 표시한다.
- [x] 배송지 입력 완료/전달 완료 상태에서 `recipientAddress`가 있을 때만 받는 주소 섹션을 표시한다.
- [x] `recipientAddress=null`이면 받는 주소 섹션 전체가 표시되지 않는다.
- [x] `status=DELIVERED`이면 전달 완료 UI와 `DELIVERED.occurredAt` 기반 배송 완료일을 표시한다.
- [x] `status=UNDELIVERABLE`이면 전달 불가 UI, 사유, 폐기·미반송 안내를 표시하고 배송지 입력·받는 주소를 숨긴다.
- [x] 문의하기는 기존 카카오 채널 문의로 연결하고, 선물 정책 확인은 임의 외부 URL을 열지 않는다.
- [x] 보낸 것과 받은 것의 상세 날짜가 UTC ISO를 기기 timezone 기준 `yyyy.MM.dd`로 표시된다.
Phase 7 구현 Task와 Task별 focused 검증은 완료했다. 상세 재조회·목록 갱신까지 명세·품질 리뷰에서 승인됐으며, 전체 local unit·assemble을 포함한 최종 완료 판정은 `P7-GATE` 실행 후 기록한다.
### 14.6 Phase 8 선물 UI 회귀 수정
- [ ] 상세 상단의 Figma에 없는 선물 이미지가 제거된다.
- [ ] 일반 진행·전달 불가·취소 완료 배지가 각각 확정된 스타일로 표시된다.
- [ ] chip이 없는 상태는 빈 배지 영역을 남기지 않는다.
- [ ] 받은 사람 약관 2개의 `(필수)` 터치 함수가 분리되고 모두 지정된 Notion URL을 열며 기존 체크·CTA 동작이 유지된다.
- [ ] 선물함 리스트의 받는 사람/보내는 사람 카드와 배송지 미입력 배너는 Figma 대조 결과 기존 구현을 유지한다.
## 15. Open Questions
현재 구현을 차단하는 미결 질문은 없다. API 계약 변경 또는 gift 리뷰/정책 route가 추가되면 이 문서의 Decision Log와 계획 범위를 먼저 갱신한다.
## 16. 요구사항 추적표
| 범위 | 계획 Phase | 검증 근거 |
|---|---:|---|
| API·DTO·repository | 1 | `GiftRepositoryTest` 및 기존 API fake 회귀 |
| 상세 presenter·5단계·개인정보 | 2 | `GiftDetailPresenterTest` |
| 상세 조회·목록 navigation | 2 | `GiftDetailViewModelTest`, `GiftInboxViewModelTest`, `GiftNavigationTest` |
| 운송장 등록 | 3 | `GiftTrackingViewModelTest`, `GiftNavigationTest` |
| V2 dialog·신청 취소 | 4 | `V2ModalDialogTest`, `GiftDetailViewModelTest` |
| Gift 네트워크 개인정보·공유 정책 보존 | 5 (`P5-R2`) | `GiftNetworkPrivacyTest`, `GiftRepositoryTest`: DI 격리·NONE 로깅·가상 개인정보 로그 미출력 |
| mutation 결과 recreate 보존 | 5 (`P5-R3`) | `GiftNavigationTest`, `GiftDetailViewModelTest`, `GiftCancelViewModelTest`: tracking·직접 취소·하위 화면 취소 성공과 CANCELED 조회 음성 회귀 |
| 일반 상세 무변경 recreate/back | 5 (`P5-R4`) | `GiftNavigationTest`: RESULT_CANCELED, 추가 GET 0회, tracking/cancel mutation 0회 |
| 통합 품질 | 5 (`P5-GATE`) | gift/modal 142개, 전체 local unit 1409개, resource/compile/lint, assembleDebug |
| 종료 문서·검증 명령 | 5 (`P5-D2`) | PRD·계획·Phase 5 리뷰·build guide 대조, snapshot diff check |
| Figma 상태·4구간 progress·정보 카드 | 6 (`P6-T1`) | `GiftDetailPresenterTest`, Figma design context와 XML/resource source 대조 |
| ASCII 운송장 입력·오류·제출 차단 | 6 (`P6-T2`) | `GiftTrackingPresenterTest`, `GiftTrackingViewModelTest`, native input XML |
| Phase 6 통합 품질·리뷰 | 6 (`P6-GATE`, `P6-R3`, `P6-REVIEW`) | gift/modal 149개, 전체 1,416개, resource/compile/ktlint/assemble, 5개 review 영역 PASS |
| 받은 선물 상세·배송지 입력 | 7 (`P7-T1`~`P7-GATE`) | 예정: `GiftDetailPresenterTest`, `GiftRecipientAddressViewModelTest`, `GiftNavigationTest`, resource/compile/ktlint |
| 상태 배지·상단 이미지·약관 함수 회귀 수정 | 8 (`P8-R1`~`P8-GATE`) | 예정: `GiftDetailPresenterTest`, `GiftNavigationTest`, Figma·source 대조, resource/compile/ktlint/assemble |
## 17. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 |
|---|---|---|---|---|---|
| `2026-10-02` | `DEC-001` | 확정 | Android만 구현한다. | 사용자 인터뷰 | 전체 |
| `2026-10-02` | `DEC-002` | 확정 | 기존 선물함 리스트 문서와 분리해 신규 PRD/계획을 작성한다. | 상세 기능은 독립 화면·API 흐름임 | 문서 구조 |
| `2026-10-02` | `DEC-003` | 확정 | 상세와 운송장 등록은 별도 Activity로 만들고 취소 완료는 상세 Activity 상태로 처리한다. | 승인된 접근안 1 | 라우팅·파일 구조 |
| `2026-10-02` | `DEC-004` | 확정 | SENT는 상대방 `recipientAddress`를 노출하지 않고 RECEIVED만 본인 주소를 표시한다. | 사용자 인터뷰 | `GIFT-PRIVACY-*` |
| `2026-10-02` | `DEC-005` | 확정 | `recipientAddress`는 `name/phoneNumber/address` 구조다. | 사용자 API 계약 보완 | DTO |
| `2026-10-02` | `DEC-006` | 확정 | `mailbox`는 전역 SODALIVE 사서함이며 recipientAddress와 구분한다. | 사용자 전제 | 상세·운송장 주소 |
| `2026-10-02` | `DEC-007` | 확정 | 취소 실패 시 dialog 유지를 위해 `V2ModalDialog`를 opt-in 방식으로 최소 확장한다. | 기존 component가 확인 즉시 닫히는 충돌 해소 | 공통 modal·취소 흐름 |
| `2026-10-02` | `DEC-008` | 확정 | gift 리뷰·정책 route가 없으므로 관련 action은 숨긴다. | 기존 경로 조사 및 사용자 규칙 | 상세 action |
| `2026-10-02` | `DEC-009` | 최초 결정 이력, 후속 `DEC-010`으로 대체 | 최초 요청에서는 문서만 작성하고 코드는 구현하지 않는다. | 최초 사용자 요청 | 초기 PRD·계획 작성 단계 |
| `2026-10-02` | `DEC-010` | 확정 | 초기 문서 전용 단계 이후 승인된 계획에 따라 Phase 1~5 구현·회귀 수정·최종 검증을 진행한다. `DEC-009`는 당시 이력으로 보존한다. | 후속 구현 승인과 Goal별 실행 기록 | 전체 구현·최종 Gate |
| `2026-10-02` | `DEC-011` | 사용자 승인 | 레거시 `AppDI.kt`에 Gift 전용 named client/Retrofit을 추가하는 좁은 예외를 허용한다. Gift 로깅은 debug/release NONE, 공유 debug BODY/release NONE과 다른 API 설정은 유지한다. | `PLAN-DEC-005`, PII finding에 대한 명시 승인 | `REV-P5-001`, `P5-R2` |
| `2026-10-02` | `DEC-012` | 확정 | mutation 후 결과 보존은 saved state의 Boolean 변경 마커만 사용한다. 재생성 후 true일 때 RESULT_OK를 복원하고 DTO·주소·전화번호·취소 응답은 추가 저장하지 않는다. | 결과 유실 회귀의 최소 수정 범위와 양성·음성 local 검증 | `REV-P5-002`, `P5-R3`, `P5-R4` |
| `2026-10-02` | `DEC-013` | 정정 | API 정상 상태 5개는 유지하되 진행 UI는 Figma의 4구간 가로 progress로 표시한다. `INSPECTION_COMPLETED`는 사서함 도착 구간과 검수일에 반영한다. | 사용자의 Figma UI 재구현 승인과 노드 `2481:19152`, `2481:19320` 직접 대조 | `GIFT-TIMELINE-001`, `P6-T1` |
| `2026-10-02` | `DEC-014` | 확정 | 기존 Activity/API 흐름을 유지하고 행 레이아웃·상태별 section binding만 재구현한다. 신규 디자인 시스템, Activity, dependency, 리뷰·정책 route는 추가하지 않는다. | 승인된 최소 변경 접근과 기존 route 조사 | Phase 6 전체 |
| `2026-10-02` | `DEC-015` | 확정 | 운송장 번호는 ASCII 숫자 10~14자리이며 15번째 문자는 native length filter로 차단한다. | 사용자 입력 계약과 Android native input/filter 공식 계약 | `GIFT-TRACKING-003`, `GIFT-TRACKING-005`, `P6-T2` |
| `2026-10-02` | `DEC-016` | 사용자 확인 | 신청 완료와 취소 완료는 기존 공통 hero 영역을 재사용하지 않는다. 전달 불가를 포함한 종료 상태에서는 progress를 표시하지 않고 Figma의 좌측 정렬 상태 안내 섹션만 사용한다. | 사용자의 Figma 직접 대조 보완 | `GIFT-STATUS-004`, `P6-T1` |
| `2026-10-02` | `DEC-017` | 확정 | Phase 7은 Android 앱 구현만 대상으로 하며 iOS 문서는 작성하지 않는다. | 사용자 확인 | Phase 7 전체 |
| `2026-10-02` | `DEC-018` | 확정 | 받은 선물 상세·배송지 입력은 기존 `GiftDetailActivity`, gift API 계층, Kakao 우편번호 Activity, 카카오 채널 문의 패턴을 확장해 구현한다. 신규 디자인 시스템은 만들지 않는다. | 저장소 패턴 조사와 사용자 전제 | `P7-T1`~`P7-T5` |
| `2026-10-02` | `DEC-019` | 확정 | 배송지 입력 성공 후 POST 응답으로 화면을 완성하지 않고 상세 GET을 다시 조회한다. | 사용자 요구와 서버 상태 source of truth | `P7-T3`, `P7-T5` |
| `2026-10-02` | `DEC-020` | 확정 | 받은 선물 전달 불가의 `선물 정책 확인`은 임의 URL을 열지 않는다. 무동작이 정책상 금지되면 `준비 중입니다.` toast만 표시한다. | 사용자 명시 조건 | `GIFT-RECEIVED-ACTION-002`, `P7-T4` |
| `2026-10-06` | `DEC-021` | 확정 | 상세 상단의 선물 이미지는 Figma에 없으므로 모든 상태에서 제거한다. | 제공된 Figma 상세 5개 노드와 현행 XML·binding 대조 | `GIFT-UI-DEBUG-001`, `P8-R1` |
| `2026-10-06` | `DEC-022` | 확정 | 상태 배지는 일반 진행 흰색, 전달 불가 빨간색, 취소 완료 회색 스타일로 분리하고 chip이 없는 상태는 숨긴다. | 제공된 Figma 상세 노드와 승인된 설계 | `GIFT-UI-DEBUG-002`, `P8-R2` |
| `2026-10-06` | `DEC-023` | 확정 | 받은 사람 약관은 실제 route 없이 이용약관·개인정보 터치 함수만 분리한다. | 사용자 선택 “함수만 분리” | `GIFT-UI-DEBUG-003`, `P8-R3` |
| `2026-10-06` | `DEC-024` | 정정 | `DEC-023`을 대체하고 받은 사람의 이용약관·개인정보 터치 시 모두 지정된 Notion URL을 외부 브라우저로 연다. | 사용자 제공 URL과 후속 명시 요청 | `GIFT-UI-DEBUG-003`, `P8-R3` |
## 18. 변경 관리
- 요구사항 변경 시 Decision Log와 관련 수용 기준을 갱신한다.
- 구현 범위가 바뀌면 `plan-task.md`를 먼저 수정한다.
- 기존 선물함 리스트 문서의 완료 기록과 당시 toast 결정을 삭제하거나 덮어쓰지 않는다.
- API field, endpoint, validation 제한 또는 route를 추정해 추가하지 않는다.