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

32 KiB

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

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

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

택배사 로컬 상수:

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 상세 조회

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을 사용한다.

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은 수정·검증 완료다.

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를 추정해 추가하지 않는다.