docs(gift): 선물 상세 요구사항과 계획을 정리한다

This commit is contained in:
2026-10-02 18:30:05 +09:00
parent 503a126033
commit d907d2cdc2
2 changed files with 1719 additions and 0 deletions
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,416 @@
# PRD: 선물 상세와 운송장 등록
## 문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 기존 Phase 1~5 완료, Figma UI 재구현 요구사항 승인·구현 준비 |
| 작성일 | `2026-10-02` |
| 최종 수정일 | `2026-10-02` |
| 대상 제품 | 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`는 별도 진행 구간을 추가하지 않고 `사서함 도착` 구간의 완료 상태와 선물 정보의 `검수일`에 반영한다.
## 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`에서 취소 완료 화면을 표시한다.
### 3.2 UX 목표
- 상단 고정 내비게이션과 하단 safe area는 기존 Android 패턴을 따른다.
- loading·content·error·retry·submit 상태에서 사용자가 현재 동작을 이해할 수 있게 한다.
- mutation 중 중복 탭을 막고 실패 시 입력 또는 취소 확인 문맥을 유지한다.
- Figma의 레이아웃·문구를 우선하되 API 상태·데이터 계약과 충돌하면 API를 우선한다.
## 4. Non-Goals
- iOS 구현 또는 iOS 문서.
- 운송장 등록 완료 후 수정 기능.
- 받는 사람 배송지 입력·수정 기능.
- 택배사 목록 API 조회.
- 신규 디자인 시스템, 신규 공통 dialog 또는 전역 event bus.
- 상대방의 `recipientAddress` 노출.
- 존재하지 않는 선물 리뷰 작성 또는 선물 정책 route 신규 구현.
- `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. 뒤로가기는 취소 전 상세·운송장 화면이 아니라 선물함으로 이동한다.
## 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` |
## 9. UI/UX Expectations
### 9.1 Figma 기준
- 운송장 등록 전 상세: `2481:19011`
- 운송장 등록 후 상세: `2481:19152`
- 전달 완료 상세: `2481:19320`
- 전달 불가: `2481:19456`
- 취소 확인 dialog: `2481:19500`
- 취소 완료: `2481:19521`
- 운송장 등록 비활성: `2481:19066`
- 운송장 등록 활성: `2481:19109`
### 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.
- 기존 color, typography, spacing, card, input, button resource를 우선 재사용한다.
- 택배사 선택은 기존 Android 선택 UI 중 가장 가까운 spinner/dialog 패턴을 재사용한다.
- 정보 카드는 단일 multiline 문자열이 아니라 Figma의 고정 label 폭과 개별 value를 가진 행 구조로 표시한다.
- Figma에만 있고 앱 route가 없는 리뷰·선물 정책 action은 이번 UI 재구현에서도 추가하지 않는다.
### 9.3 취소 dialog 문구
- 제목: `신청 취소`
- 본문 첫 줄: `{크리에이터}에게 보내는 선물을 취소할까요?`
- 본문 둘째 줄: `선물 보내기 규정에 따라 선물 취소 및 사용한 캔이 모두 환불됩니다.`
- 왼쪽: `나가기`
- 오른쪽: `취소하기`
## 10. 날짜 표시 정책
- 입력은 UTC ISO 문자열이다.
- 앱의 기존 날짜 formatter 패턴에 맞춰 기기 timezone으로 변환한다.
- progress: `MM.dd`.
- 정보 카드·신청 요약·취소 상세: `yyyy.MM.dd`.
- null 또는 파싱 실패 날짜는 임의 날짜를 만들지 않고 해당 값 또는 행을 숨긴다.
## 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`을 사용한다.
## 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`은 수정·검증 완료다.
## 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 |
## 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` |
## 18. 변경 관리
- 요구사항 변경 시 Decision Log와 관련 수용 기준을 갱신한다.
- 구현 범위가 바뀌면 `plan-task.md`를 먼저 수정한다.
- 기존 선물함 리스트 문서의 완료 기록과 당시 toast 결정을 삭제하거나 덮어쓰지 않는다.
- API field, endpoint, validation 제한 또는 route를 추정해 추가하지 않는다.