# PRD: 선물 상세와 운송장 등록 ## 문서 정보 | 항목 | 내용 | |---|---| | 문서 상태 | 기존 Phase 1~7 완료, Phase 8 진행 이력 보존, Phase 9 딥링크·한글 브랜드 표기 기준 확정 | | 작성일 | `2026-10-02` | | 최종 수정일 | `2026-10-08` | | 대상 제품 | 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를 렌더링한다. 보낸 선물 상세, 운송장 등록, 신청 취소의 완료 이력과 검증 기록은 보존한다. Phase 9에서는 기존 외부 딥링크·푸시의 단일 진입점인 `DeepLinkActivity` 흐름에 `gift-detail/{applicationNo}`를 추가한다. 별도 딥링크 Activity는 만들지 않으며 foreground 직접 라우팅과 cold start의 `SplashActivity` → `MainV2Activity` 전달 흐름을 모두 유지한다. 또한 한국어 기본 resource에서 gift 화면에 표시되는 브랜드명 `SODALIVE`를 `소다라이브`로 바꾸고 영어·일본어 번역은 유지한다. ## 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. 실패하면 기존 오류 표시와 같은 신청번호 재시도를 제공한다. 7. `voiceon://gift-detail/{applicationNo}` 또는 `voiceon-test://gift-detail/{applicationNo}`로 진입하면 기존 딥링크 흐름을 통해 같은 신청번호의 상세를 연다. ### 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 External URI / Push deep link -> DeepLinkActivity -> foreground: GiftDetailActivity(applicationNo) -> cold start: SplashActivity -> MainV2Activity -> GiftDetailActivity(applicationNo) ``` - `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` 조회는 재생성 후에도 성공 결과를 만들지 않는다. - custom scheme은 빌드별 기존 `${URISCHEME}` 설정을 그대로 사용하며 `voiceon`과 `voiceon-test`를 production 코드에서 별도 분기하지 않는다. - `gift-detail`의 첫 path segment는 숫자로 변환하지 않고 신청번호 문자열 그대로 `GiftDetailActivity`에 전달한다. ## 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` | ### 8.13 Phase 9 선물 상세 딥링크와 한국어 브랜드 표기 | ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 | |---|---|---|---|---| | `GIFT-DEEPLINK-001` | 확정 | 기존 `DeepLinkActivity` 중심 경로에서 `gift-detail/{applicationNo}`를 인식한다. | 별도 exported gift 진입 Activity 없이 외부 custom scheme과 FCM deep link가 기존 단일 진입점을 사용한다. | `P9-T1` | | `GIFT-DEEPLINK-002` | 확정 | foreground와 cold start 모두 동일한 신청번호의 `GiftDetailActivity`를 연다. | `A-1002609300001` 같은 문자열 신청번호가 손실 없이 전달되고 blank 또는 path 누락 시 상세를 열지 않는다. | `P9-T1`, `P9-T2` | | `GIFT-DEEPLINK-003` | 확정 | 빌드별 URI scheme은 기존 Manifest placeholder로 구분한다. | `voiceon`, `voiceon-test`를 위한 production 분기나 중복 intent-filter를 추가하지 않는다. | `P9-T1` | | `GIFT-I18N-001` | 확정 | 한국어 기본 resource의 gift 화면 브랜드명 `SODALIVE`를 `소다라이브`로 표시한다. | `kr.co.vividnext.sodalive.v2.gift` 화면에서 사용하는 한국어 문자열의 `SODALIVE`가 남지 않고 영어·일본어 resource의 `SODALIVE`는 유지된다. | `P9-T3` | ### 8.14 Phase 10 선물 상세 라벨 보정 | ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 | |---|---|---|---|---| | `GIFT-I18N-002` | 확정 | 선물 정보의 닉네임 label은 locale별 크리에이터 명칭을 표시한다. | `gift_detail_counterpart`가 한국어 `크리에이터`, 영어 `Creator`, 일본어 `クリエイター`이며 기존 resource key와 Activity 참조는 유지된다. | `P10-T1` | | `GIFT-STATUS-005` | 확정 | `CANCELED` 상세 상단 배지는 취소 완료 문구를 표시한다. | `CANCELED_LABEL`이 상세 전용 `gift_detail_canceled_header`를 사용해 한국어 `취소 완료`, 영어 `Cancellation complete`, 일본어 `キャンセル完了`로 해석되고 선물함의 신청 취소 문구는 유지된다. | `P10-T1` | | `GIFT-I18N-003` | 확정 | 선물 상세와 운송장 등록의 공통 사서함 섹션 title은 locale별 받는 사서함 명칭을 표시한다. | `gift_tracking_destination`이 한국어 `받는 사서함`, 영어 `Receiving mailbox`, 일본어 `受取私書箱`이며 기존 key·두 layout 참조·`mailbox` 데이터 바인딩은 유지된다. | `P10-T2` | ## 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>`를 사용한다. - 성공 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` | 중첩 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 대조 결과 기존 구현을 유지한다. ### 14.7 Phase 9 선물 상세 딥링크·한글 브랜드 표기 - [ ] 외부 custom scheme과 FCM deep link가 기존 `DeepLinkActivity`를 통해 `gift-detail` 신청 상세로 이동한다. - [ ] foreground와 cold start에서 신청번호 문자열이 동일하게 보존된다. - [ ] path가 없거나 신청번호가 blank이면 상세 Activity를 열지 않는다. - [ ] 별도 exported gift 딥링크 Activity와 scheme별 production 분기를 추가하지 않는다. - [ ] 한국어 gift 화면은 `소다라이브`를 표시하고 영어·일본어 번역은 기존 `SODALIVE`를 유지한다. ### 14.8 Phase 10 선물 상세 라벨 보정 - [x] 선물 정보 닉네임 label이 한국어 `크리에이터`, 영어 `Creator`, 일본어 `クリエイター`로 표시된다. - [x] `CANCELED` 상세 상단 배지가 locale별 취소 완료 문구를 표시하고 선물함의 신청 취소 문구는 변경되지 않는다. - [x] 선물 상세와 운송장 등록의 사서함 섹션 title이 한국어 `받는 사서함`, 영어 `Receiving mailbox`, 일본어 `受取私書箱`으로 표시되고 기존 사서함 데이터는 유지된다. ## 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 | | 선물 상세 딥링크·한국어 브랜드 표기 | 9 (`P9-T1`~`P9-GATE`) | 예정: 딥링크 parser/routing local test, `GiftNavigationTest`, 한국어 resource 검색, resource/compile/ktlint/assemble | | 선물 상세 크리에이터·취소 완료 라벨 | 10 (`P10-T1`) | `GiftDetailViewModelTest`, locale resource 검색, resource/compile/ktlint | | 선물 상세·운송장 등록 사서함 title | 10 (`P10-T2`) | `GiftDetailViewModelTest`, 두 layout의 공유 resource 참조, resource/compile/ktlint | ## 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` | | `2026-10-08` | `DEC-025` | 확정 | `gift-detail`은 별도 진입 Activity를 만들지 않고 기존 외부 딥링크·푸시의 단일 진입점인 `DeepLinkActivity` 흐름에 추가한다. | Manifest, FCM, 알림 목록의 실제 진입 경로 조사와 사용자 정정 승인 | `GIFT-DEEPLINK-001`, `P9-T1`, `P9-T2` | | `2026-10-08` | `DEC-026` | 사용자 승인 | 중앙 딥링크 흐름 유지에 필요한 최소 범위로 레거시 `DeepLinkActivity` 수정을 허용한다. | 별도 v2 gift 진입 Activity가 기존 경로와 중복된다는 조사 결과 | `GIFT-DEEPLINK-001`, `P9-T1` | | `2026-10-08` | `DEC-027` | 확정 | `voiceon`과 `voiceon-test`는 기존 `${URISCHEME}` 빌드 설정을 사용하고 기능 코드에서 구분하지 않는다. | 사용자 명시 요청과 현행 Manifest 구조 | `GIFT-DEEPLINK-003`, `P9-T1` | | `2026-10-08` | `DEC-028` | 확정 | 브랜드명 변경은 한국어 기본 resource만 대상으로 하고 영어·일본어 `SODALIVE`는 유지한다. | 사용자 인터뷰 답변 B | `GIFT-I18N-001`, `P9-T3` | | `2026-10-08` | `DEC-029` | 확정 | `gift_detail_counterpart` key를 유지하고 한국어·영어·일본어 값을 각각 `크리에이터`, `Creator`, `クリエイター`로 변경한다. | 사용자 선택 권장안 1 | `GIFT-I18N-002`, `P10-T1` | | `2026-10-08` | `DEC-030` | 확정 | 상세 `CANCELED_LABEL`은 기존 `gift_detail_canceled_header`를 재사용하고 선물함용 `gift_inbox_canceled`는 변경하지 않는다. | 잘못된 resolver 매핑 원인 확인과 사용자 선택 권장안 1 | `GIFT-STATUS-005`, `P10-T1` | | `2026-10-08` | `DEC-031` | 확정 | 두 화면이 공유하는 `gift_tracking_destination` key를 유지하고 한국어·영어·일본어 값을 각각 `받는 사서함`, `Receiving mailbox`, `受取私書箱`으로 변경한다. | 사용자 다국어 변경 승인 | `GIFT-I18N-003`, `P10-T2` | ## 18. 변경 관리 - 요구사항 변경 시 Decision Log와 관련 수용 기준을 갱신한다. - 구현 범위가 바뀌면 `plan-task.md`를 먼저 수정한다. - 기존 선물함 리스트 문서의 완료 기록과 당시 toast 결정을 삭제하거나 덮어쓰지 않는다. - API field, endpoint, validation 제한 또는 route를 추정해 추가하지 않는다.