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

56 KiB

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 운송장 화면, Phase 4 취소 ViewModel, Phase 4 취소 화면, Phase 5 최종 회귀

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. 정보 구조와 라우팅

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

택배사 로컬 상수:

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<ApiResponse<T>>를 사용한다.
  • 성공 payload는 response.data다.
  • success=false, data=null, transport 오류는 성공 화면으로 처리하지 않는다.

11.2 상세 조회

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 운송장 등록

POST /api/v2/gifts/{applicationNo}/tracking
Content-Type: application/json

{
  "courierCompanyName": "한진택배",
  "trackingNumber": "123456789012"
}
  • response data는 applicationNo, status, statusName, courierCompanyName, trackingNumber, trackingRegisteredAt, recipientAddressDeadlineAt을 사용한다.

11.4 신청 취소

POST /api/v2/gifts/{applicationNo}/cancel
  • request body는 없다.
  • response data는 applicationNo, status, statusName, priceCan, canceledAt을 사용한다.

11.5 받은 선물 배송지 입력

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 완료 이력)

  • 목록 item이 applicationNo 상세로 이동한다.
  • 상세 API의 response.data로 상태별 화면을 렌더링한다.
  • 정상 progress 5개가 순서대로 표시된다.
  • trackingRequired=true에서만 운송장 작성 흐름이 동작한다.
  • 취소 확인 전에는 취소 API를 호출하지 않는다.
  • 취소 실패 시 dialog가 유지되고 성공 시 취소 완료 상태로 전환된다.
  • 운송장 등록 성공 후 상세를 재조회한다.

14.2 개인정보·UI (Phase 1~5 완료 이력)

  • SENT에서 recipientAddress가 노출되지 않는다.
  • RECEIVED에서 본인의 recipientAddress만 조건부 표시된다.
  • mailbox는 SODALIVE 사서함으로만 표시된다.
  • Figma 구조와 문구를 source/resource 대조로 확인했으며 5단계·API 데이터 계약을 우선한다.
  • review/policy route를 새로 만들지 않는다.
  • Gift 요청·응답은 전용 NONE 로깅 경로를 사용하며 공유 네트워크 정책을 바꾸지 않는다.

Figma/layout 증거는 소스와 리소스 대조에 한정한다. 화면 표현 로직과 라우팅은 local unit test로 검증했으며 기기·에뮬레이터·androidTest·스크린샷·시각 QA는 제외했다. 위 체크는 실기기 렌더링이나 픽셀 일치 검증을 뜻하지 않는다.

14.3 품질 (Phase 1~5 완료 이력)

  • focused gift/modal local unit test가 통과한다.
  • 전체 local unit test, resource merge, Kotlin compile, ktlint가 통과한다.
  • 모든 확정 요구사항이 plan-task.md의 Task와 검증 증거에 연결된다.
  • mutation 성공 결과는 recreate 후 보존되고 변경 없는 일반 상세·CANCELED 조회는 성공 결과를 만들지 않는다.

14.4 Phase 6 Figma UI 재구현

  • 신청 완료·운송장 등록·등록 오류·등록 후 상세·전달 완료·전달 불가·취소 완료의 콘텐츠 계층이 대응 Figma 노드와 일치한다.
  • 정상 진행 API 상태 5개가 Figma의 4구간 progress에 손실 없이 매핑된다.
  • 신청 완료·전달 불가·취소 완료에는 공통 hero illustration과 progress가 표시되지 않는다.
  • 취소 완료가 동적 안내문과 7행 취소 상세 카드를 표시한다.
  • 운송장 번호는 ASCII 숫자 10~14자리만 유효하고 15번째 문자는 입력되지 않는다.
  • layout 속성을 직접 검증하는 테스트를 추가하지 않고 presenter/validation의 화면 결정 로직을 local unit test로 검증한다.
  • 관련 local unit, resource merge, Kotlin compile, ktlint와 debug assemble이 통과한다.

기존 14.114.3의 완료 체크는 Phase 15 당시 증거를 보존한다. 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 받은 선물 상세·배송지 입력

  • 받은 선물 상세 진입 시 GET /api/v2/gifts/{applicationNo}를 호출하고 direction=RECEIVED 상태만 받은 선물 UI로 렌더링한다.
  • recipientAddressRequired=true이면 배송지 입력 form과 약관 2개, 선물 받기 CTA가 표시된다.
  • 필수 입력 또는 약관이 누락되면 배송지 POST를 호출하지 않는다.
  • 배송지 POST request body가 API 명세와 일치하고 submit 중 중복 요청이 없다.
  • 배송지 입력 성공 후 상세를 재조회하고 배송지 입력 완료 UI를 표시한다.
  • 배송지 입력 완료/전달 완료 상태에서 recipientAddress가 있을 때만 받는 주소 섹션을 표시한다.
  • recipientAddress=null이면 받는 주소 섹션 전체가 표시되지 않는다.
  • status=DELIVERED이면 전달 완료 UI와 DELIVERED.occurredAt 기반 배송 완료일을 표시한다.
  • status=UNDELIVERABLE이면 전달 불가 UI, 사유, 폐기·미반송 안내를 표시하고 배송지 입력·받는 주소를 숨긴다.
  • 문의하기는 기존 카카오 채널 문의로 연결하고, 선물 정책 확인은 임의 외부 URL을 열지 않는다.
  • 보낸 것과 받은 것의 상세 날짜가 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 선물 상세 라벨 보정

  • 선물 정보 닉네임 label이 한국어 크리에이터, 영어 Creator, 일본어 クリエイター로 표시된다.
  • CANCELED 상세 상단 배지가 locale별 취소 완료 문구를 표시하고 선물함의 신청 취소 문구는 변경되지 않는다.
  • 선물 상세와 운송장 등록의 사서함 섹션 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를 추정해 추가하지 않는다.