# PRD: 선물함 리스트 페이지 ## 문서 정보 | 항목 | 내용 | |---|---| | 문서 상태 | 구현 기준 확정 | | 작성일 | `2026-10-01` | | 최종 수정일 | `2026-10-08` | | 대상 제품 | 선물함 리스트 페이지 UI·목록 API 연동 및 마이 탭 진입점 | | 작성자·결정권자 | 사용자 요청 기준 | | 관련 API Contract | `GET /api/v2/gifts?type=ALL&page=0&size=20` | | 관련 구현 계획 | `docs/20261001_선물함_리스트_페이지/plan-task.md` | | 관련 review | 없음 | ### 요구사항 상태 | 상태 | 의미 | 구현 처리 | |---|---|---| | 확정 | 이번 구현 기준으로 사용 | `plan-task.md`의 Task와 완료 증거로 추적 | | 외부 의존 | 현재 API 응답만으로 완전 표시가 불가능 | API 보강 전에는 문서의 안전한 기본값만 구현 | | 제외 | 이번 범위에서 구현하지 않음 | Decision Log에 제외 이유 기록 | ## 1. Overview 사용자가 본인이 보낸 선물 신청 내역과 본인이 받을 선물 내역을 한 화면에서 확인하는 선물함 리스트 페이지를 만든다. 실제 API는 관점별 호출을 분리하지 않고 `type=ALL`로 한 번 조회하며, 각 item의 `direction` 값에 따라 보낸 선물 카드와 받은 선물 카드를 다르게 렌더링한다. 한국에서 접속하고 앱의 유효 언어가 한국어인 로그인 사용자는 마이 탭의 첫 번째 기능 아이콘으로 선물함에 진입할 수 있다. ## 2. Problem Statement - 현재 앱에는 선물 신청 이후 사용자가 신청/수령 예정 내역을 확인할 선물함 리스트 화면이 필요하다. - Figma는 보낸 선물 관점과 받은 선물 관점을 나누어 보여주지만 실제 API는 `ALL` 단일 호출로 내려온다. - 목록 API에 배송지 등록 여부, 배송지 입력 마감일, 취소일이 추가되어 받은 선물의 배송지 입력 여부와 동적 마감 문구, 취소 날짜를 표시할 수 있다. 문제를 해결했다는 판단은 `GET /api/v2/gifts?type=ALL&page=0&size=20` 응답을 기존 Android 패턴으로 조회하고, `direction`과 `status`에 따라 요구된 카드/빈 상태/배너 UI가 표시되는 것으로 한다. ## 3. Goals ### 3.1 제품 목표 - 선물함 진입 시 첫 페이지를 `type=ALL`, `page=0`, `size=20`으로 한 번 조회한다. - `hasNext=true`이면 스크롤 하단에서 다음 page를 추가 조회한다. - `items[].direction == SENT`는 보낸 선물 카드로, `RECEIVED`는 받은 선물 카드로 표시한다. - 리스트는 서버 응답 순서를 유지한다. 서버는 현재 `createdAt desc, id desc`로 정렬한다. - 카드 또는 배송지 입력 안내 배너 탭 시 item의 `applicationNo`로 선물 상세를 연다. - 받은 선물은 `UNDELIVERABLE`을 제외하고 `recipientAddressRegistered`로 배송지 입력 전·후 UI를 구분한다. - API UTC 시각은 `v2.gift` 화면에서 디바이스 타임존으로 변환해 표시한다. - 한국 접속·한국어 유효 언어 조건을 모두 충족하면 마이 탭 기능 아이콘 목록의 첫 번째에 선물함 진입점을 표시한다. ### 3.2 UX 목표 - 상단 뒤로가기 내비게이션은 고정하고, 내비게이션 아래 콘텐츠만 스크롤한다. - Figma에 보이는 `신청 내역`, `선물 내역` 섹션 타이틀은 실제 화면에 노출하지 않는다. - 보낸 선물 관점 빈 상태는 안내 배너만 표시하고 별도 empty title/body를 추가하지 않는다. - 받은 선물 관점 빈 상태는 중앙 empty UI와 `의견 남기기` 버튼을 표시한다. - 최초 로딩, 실패, 재시도, pagination loading은 기존 앱의 리스트/토스트/로딩 패턴을 재사용한다. ## 4. Non-Goals - `SENT`, `RECEIVED` 별도 목록 API 호출. - 클라이언트 임의 재정렬. - 누락되거나 잘못된 배송지 입력 마감일을 임의 값으로 대체해 표시. - 선물 상세 페이지 자체 구현. 목록은 후속 상세 구현의 `GiftDetailActivity`로 연결만 한다. - 사용자 승인을 받은 `MyPageFragment`의 선물함 진입점 최소 연결 외 레거시 코드 직접 수정. - `app/src/androidTest`, `connectedDebugAndroidTest`, 기기·에뮬레이터 UI 조작, 스크린샷 기반 시각 QA. ## 5. Target Users and Permissions ### 5.1 사용자 | 사용자 | 목표 | 주요 작업 | 사용 환경 | |---|---|---|---| | 팬 사용자 | 본인이 신청한 선물 내역 확인 | 선물함 조회, 상태 확인 | Android 앱 | | 크리에이터 사용자 | 본인이 받을 선물 내역 확인 | 배송지 입력 필요 내역 확인, 상태 확인, 문의 이동 | Android 앱 | ### 5.2 권한 - 인증 주체: 기존 앱 로그인 사용자. - 인증 방식: 기존 `SharedPreferenceManager.token` 기반 `Authorization: Bearer ...` 패턴을 재사용한다. - 거부 조건: API 401/403 또는 기존 로그인 세션 오류 정책을 따른다. - 리소스 소유권: 서버가 로그인 사용자 기준으로 보낼/받을 수 있는 선물만 반환한다. ## 6. 핵심 사용자 흐름 1. 사용자가 선물함 화면에 진입한다. 2. 상단 고정 내비게이션에 제목 `선물함`과 기존 뒤로가기 버튼 패턴이 표시된다. 3. 앱은 `GET /api/v2/gifts?type=ALL&page=0&size=20`을 호출한다. 4. 성공하면 서버 응답 순서대로 item을 표시한다. 5. `direction=SENT` item은 보낸 선물 카드로 표시한다. 6. `direction=RECEIVED` item은 받은 선물 카드로 표시한다. 7. 하단 스크롤 도달 시 `hasNext=true`이면 다음 page를 추가 조회해 기존 목록 뒤에 붙인다. 8. 카드 또는 배송지 입력 안내 배너를 누르면 item의 `applicationNo`로 선물 상세를 연다. 9. API 실패 시 기존 toast/dialog 패턴과 재시도 UI를 제공하고 기존 입력/스크롤 상태를 깨지 않는다. ## 7. 정보 구조와 라우팅 ```text GiftInboxActivity -> GiftDetailActivity(applicationNo) -> 설정 페이지의 카카오 문의하기와 동일한 문의 화면 ``` - 신규 화면 단위: `GiftInboxActivity`. - 마이 탭의 선물함 기능 아이콘은 `GiftInboxActivity.newIntent(context)`로 기본 `ALL` 관점에 진입한다. - Activity 위치: `kr.co.vividnext.sodalive.v2.gift` 하위. - 진입 관점 extra: `EXTRA_GIFT_INBOX_VIEW_MODE`는 `SENT`, `RECEIVED`, `ALL` 중 하나로 계획한다. 기본값은 `ALL`이다. - API 호출은 진입 관점과 무관하게 항상 `type=ALL`만 사용한다. - 빈 상태 판정은 진입 관점과 사용자 유형으로 결정한다. `SENT`로 진입했고 표시할 보낸 선물이 없으면 보낸 선물 빈 상태, `RECEIVED`로 진입했고 표시할 받은 선물이 없으면 받은 선물 빈 상태를 사용한다. - `ALL` 진입에서 전체 목록이 비었을 때 현재 사용자가 크리에이터이면 받은 선물 없음 UI를 표시하고, 일반 회원이면 보낸 선물 신청 내역 없음 UI를 표시한다. 현재 선물은 크리에이터만 받을 수 있고 일반 회원은 받을 수 없다. - 카드나 배송지 입력 배너를 터치하면 item의 `applicationNo`만 `GiftDetailActivity`에 전달한다. - 받은 선물 empty 또는 하단 `문의하기`/`의견 남기기` 버튼은 설정 페이지의 카카오 문의하기와 동일한 화면으로 연결한다. ## 8. 기능 요구사항 ### 8.1 API 조회와 pagination | ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | |---|---|---|---|---| | `GIFT-INBOX-API-001` | 확정 | 선물함 목록은 항상 `GET /api/v2/gifts`에 `type=ALL&page=0&size=20`으로 첫 페이지를 조회한다. | 테스트 double이 `type=ALL`, `page=0`, `size=20` 호출을 기록한다. | `P1-T1` | | `GIFT-INBOX-API-002` | 확정 | `hasNext=true`이고 하단에 도달하면 다음 page를 추가 조회한다. | page 1 요청 후 기존 목록 뒤에 append된다. | `P2-T2` | | `GIFT-INBOX-API-003` | 확정 | pull-to-refresh가 기존 패턴으로 가능하면 page를 0으로 초기화하고 다시 조회한다. | refresh 후 첫 페이지 목록으로 교체된다. | `P2-T3` | | `GIFT-INBOX-API-004` | 확정 | API 실패 시 toast/dialog와 재시도 액션을 제공한다. | 기존 content가 있으면 유지하고 오류 feedback을 표시한다. | `P2-T4` | ### 8.2 item 렌더링 | ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | |---|---|---|---|---| | `GIFT-INBOX-UI-001` | 확정 | `direction=SENT`는 보낸 선물 카드로 렌더링한다. | 상태명, 날짜 라벨, 상대 표시 영역, 사이즈/카테고리, chevron이 표시된다. | `P1-T2`, `P3-T1` | | `GIFT-INBOX-UI-002` | 정정 | `direction=RECEIVED`는 받은 선물 아이템으로 렌더링한다. `UNDELIVERABLE`은 기존 일반 카드를 유지하고, 그 외 상태에서 `recipientAddressRegistered=false`이면 일반 카드 대신 기존 3문구 Address 아이템을 사용한다. | 배송지 미입력 선물은 `팬이 보낸 선물이 있어요!`, 배송지 입력 안내, 동적 마감 경고와 chevron을 표시하고 같은 신청번호의 일반 카드를 중복 표시하지 않는다. | `P1-T2`, `P3-T1`, `P7-R1`, `P8-T2` | | `GIFT-INBOX-UI-003` | 확정 | `신청 내역`, `선물 내역` 텍스트는 노출하지 않는다. | string/resource/layout에 화면 노출용 section title로 추가하지 않는다. | `P3-GATE` | | `GIFT-INBOX-UI-004` | 확정 | 상단 내비게이션은 고정하고 하단 콘텐츠만 스크롤한다. | root는 고정 header와 scroll/recycler content 영역으로 분리된다. | `P3-T2` | | `GIFT-INBOX-UI-005` | 정정 | 보낸 카드·받은 카드·배송지 미입력 Address 아이템 터치 시 해당 `applicationNo`로 선물 상세를 연다. | 각 목록 아이템이 자신의 신청번호로 `GiftDetailActivity`를 한 번 실행한다. | `P7-R1`, 상세 문서 `P2-T3`, `P7-T5` | | `GIFT-INBOX-UI-006` | 확정 | `status=CANCELED`이면 Figma `2481:19434`처럼 카드 우측 상단에 취소 날짜를 표시한다. | `canceledAt`을 디바이스 타임존의 `yyyy.MM.dd 취소`로 표시하며, 예외적으로 null이면 `createdAt`을 사용한다. | `P8-T2` | ### 8.3 상태 문구 매핑 | ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | |---|---|---|---|---| | `GIFT-INBOX-STATUS-001` | 확정 | 보낸 선물 상태 코드를 요구사항 표의 표시 문구로 매핑한다. | `RECEIVED`는 `운송장 등록 필요`, `CANCELED`는 `신청 취소`로 변환된다. | `P1-T2` | | `GIFT-INBOX-STATUS-002` | 정정 | 받은 선물의 배송지 입력 전·후 표시 형태를 API 필드로 결정한다. | `UNDELIVERABLE`은 기존 일반 카드를 유지한다. 그 외 상태는 `recipientAddressRegistered=false`이면 Address 아이템, `true`이면 기존 상태 카드를 표시한다. | `P1-T2`, `P7-R1`, `P8-T2` | | `GIFT-INBOX-STATUS-003` | 정정 | 배송지 미입력 Address 아이템은 `recipientAddressDeadlineAt`까지 남은 일수를 표시한다. | UTC instant 차이를 24시간 단위로 올림해 `*{N}일 이내로 입력하지 않으면 선물이 사라져요.`를 표시한다. 미입력 상태에서 null 또는 만료된 정상 상태는 발생하지 않는 API 계약으로 처리한다. | `P8-T1`, `P8-T2` | | `GIFT-INBOX-STATUS-004` | 확정 | `v2.gift`의 API UTC 시각은 디바이스 타임존으로 변환한 뒤 기존 화면별 형식으로 표시한다. | 리스트·상세·운송장의 날짜 경계 테스트에서 디바이스 타임존에 따른 날짜가 표시된다. | `P8-T1`, `P8-T3` | ### 8.4 빈 상태와 배너 | ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | |---|---|---|---|---| | `GIFT-INBOX-EMPTY-001` | 확정 | 보낸 선물 관점 빈 상태는 상단 안내 배너만 표시한다. | 별도 empty title/body가 없다. | `P3-T3` | | `GIFT-INBOX-EMPTY-002` | 확정 | 받은 선물 관점 빈 상태는 중앙 empty title/body와 `의견 남기기` 버튼을 표시한다. | 지정 문구와 버튼이 표시된다. | `P3-T3` | | `GIFT-INBOX-EMPTY-003` | 확정 | `ALL` 진입에서 전체 목록이 비었을 때 크리에이터이면 받은 선물 없음, 일반 회원이면 보낸 선물 신청 내역 없음 형태로 표시한다. | 사용자 유형이 creator이면 `RECEIVED` empty, 아니면 `SENT` empty 정책을 적용한다. | `P3-T3` | | `GIFT-INBOX-BANNER-001` | 확정 | 보낸 선물 콘텐츠에는 안전 배송 안내 배너를 표시한다. | 제목/본문이 요구 문구와 일치한다. | `P3-T2` | | `GIFT-INBOX-BANNER-002` | 확정 | 받은 선물 콘텐츠에는 배송지 입력 기간 안내 배너를 표시한다. | 제목/본문이 요구 문구와 일치한다. | `P3-T2` | | `GIFT-INBOX-BANNER-003` | 정정 | 배송지 입력이 필요한 받은 선물은 별도 상단 배너가 아니라 해당 선물 위치의 파란 Address 아이템으로 표시한다. | `UNDELIVERABLE`이 아니고 `recipientAddressRegistered=false`인 받은 선물마다 Address 아이템이 하나씩 생성되며 같은 신청번호의 일반 카드는 생성되지 않는다. 각 아이템은 자신의 상세로 이동하고 개별 마감일까지 남은 일수를 표시한다. | `P7-R1`, `P8-T2`, 상세 문서 `P7-T5` | | `GIFT-INBOX-INQUIRY-001` | 확정 | 받은 선물 empty 또는 하단 문의 버튼은 설정 페이지의 카카오 문의하기와 동일한 페이지로 연결한다. | 기존 설정 페이지 카카오 문의하기 intent/URL 패턴을 재사용한다. | `P3-T5` | ### 8.5 마이 탭 진입점 | ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | |---|---|---|---|---| | `GIFT-INBOX-ENTRY-001` | 확정 | 로그인 사용자의 마이 탭 기능 아이콘 목록에서 선물함을 첫 번째 항목으로 제공한다. | 표시 조건 충족 시 index 0의 아이콘은 `ic_my_present`, 레이블은 `선물함`이다. | `P5-T1`, `P5-T2` | | `GIFT-INBOX-ENTRY-002` | 확정 | 국가 코드가 `KR`이고 앱의 유효 언어가 `ko`일 때만 선물함 항목을 표시한다. | 한국/한국어 조합만 true이고 한국/비한국어, 비한국/한국어, 비한국/비한국어 조합은 false다. 빈 국가 코드는 기존 정책대로 `KR`로 처리한다. | `P5-T1` | | `GIFT-INBOX-ENTRY-003` | 확정 | 선물함 항목을 누르면 기본 `ALL` 관점의 `GiftInboxActivity`로 이동한다. | 클릭 callback이 `GiftInboxActivity.newIntent(requireContext())`를 시작한다. | `P5-T2` | ### 8.6 상대방 프로필 | ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | |---|---|---|---|---| | `GIFT-INBOX-PROFILE-001` | 확정 | item의 `counterpartMemberId: Long`, `counterpartNickname: String`, `counterpartProfileImageUrl: String?`를 수용한다. `SENT`의 상대는 수신 크리에이터, `RECEIVED`의 상대는 발신 팬이다. | 두 방향의 상대 ID·닉네임·이미지 URL이 DTO에서 카드 UI 모델로 전달된다. | `EXT-001`, `P6-T1`, `P6-T2` | | `GIFT-INBOX-PROFILE-002` | 확정 | 두 카드의 프로필 행에 이미지와 상대방 닉네임을 표시한다. null/blank 이미지 URL은 null로 정규화하고 `ic_placeholder_profile`을 사용한다. | 유효 URL은 유지하고 null·빈 문자열·공백 문자열은 null로 매핑한다. 기존 Coil로 이미지와 placeholder를 바인딩한다. | `P6-T1`, `P6-T2`, `P6-T3` | | `GIFT-INBOX-PROFILE-003` | 정정 | `SENT`는 프로필 아래 `sizeName · categoryName`을 유지하고, `RECEIVED`는 상단 프로필·날짜와 본문 상태를 유지한다. 기존 조회·direction·pagination·상세 이동을 변경하지 않는다. | `ALL/0/20` 최초 조회, 다음 page append 및 카드·배너 상세 이동 회귀 테스트가 통과한다. | `P6-T3`, `P6-GATE`, 상세 문서 `P7-T5` | ## 9. UI/UX Expectations ### 9.1 Figma 기준 - 보낸 선물, 신청 내역 있음: `2481:19382`. - 보낸 선물, 신청 내역 없음: `2520:35587`. - 받은 선물, 받은 선물 없음: `2531:36283`. - 받은 선물, 받은 선물 있음: `2531:36194`. - 받은 선물, 상태별 카드 표시: `2531:36237`. - 받은 선물, 배송지 미입력 Address 아이템: `2531:36243`. - 보낸 선물, 신청 취소 카드: `2481:19434`. - 사용자 요구사항이 Figma와 충돌하면 사용자 요구사항을 우선한다. ### 9.2 디자인과 component 원칙 - Android 기존 디자인 시스템, resource token, BaseActivity, ViewBinding, RecyclerView, toast/loading/navigation 패턴을 재사용한다. - 기존 선물 보내기 구현의 `GiftApi`, `GiftRepository`, `GiftSendRequestViewModel` 패턴을 따른다. - 신규 `Activity`, `ViewModel`, DTO, adapter, presenter는 `kr.co.vividnext.sodalive.v2.gift` 하위에 작성한다. - 두 개 이상 화면에서 재사용할 확정 근거가 생기기 전에는 shared component로 올리지 않는다. ### 9.3 화면 상태 - Loading: 최초 조회 중 기존 리스트 loading 또는 loading dialog/skeleton 패턴을 사용한다. - Content: 방향별 상단 안내 배너, 배송지 미입력 선물별 Address 아이템, 나머지 카드 리스트, 하단 문의 버튼을 콘텐츠 스크롤 영역에 포함한다. - Empty: 진입 관점에 따라 보낸 선물 empty 또는 받은 선물 empty를 표시한다. `ALL` 진입의 전체 빈 목록은 사용자 유형으로 분기한다. - Error: 첫 페이지 실패는 retry UI를 표시하고, append 실패는 기존 목록을 유지하며 feedback을 표시한다. ## 10. API 계약 ### 10.1 Endpoint ```http GET /api/v2/gifts?type=ALL&page=0&size=20 Authorization: Bearer {token} ``` ### 10.2 Response envelope ```json { "success": true, "data": { "totalCount": 2, "items": [ { "applicationNo": "A-1002609300001", "direction": "SENT", "counterpartMemberId": 1001, "counterpartNickname": "예시 크리에이터", "counterpartProfileImageUrl": null, "status": "RECEIVED", "statusName": "접수 완료", "priceCan": 80, "categoryName": "아크릴/스탠드", "sizeName": "소형", "createdAt": "2026-09-18T03:00:00Z", "recipientAddressRegistered": true, "recipientAddressDeadlineAt": null, "canceledAt": null } ], "page": 0, "size": 20, "hasNext": false }, "message": "" } ``` ### 10.3 상대방 프로필 계약 | 필드 | 타입 | 의미 | |---|---|---| | `counterpartMemberId` | `Long` | 상대방 회원 ID | | `counterpartNickname` | `String` | 상대방 닉네임 | | `counterpartProfileImageUrl` | `String?` | 상대방 프로필 이미지 URL. null 또는 blank이면 `ic_placeholder_profile` 표시 | | `recipientAddressRegistered` | `Boolean` | 받은 사람이 배송지를 등록했는지 여부. 받은 선물의 Address 아이템 분기에 사용 | | `recipientAddressDeadlineAt` | `String?` | 배송지 입력 마감 UTC 시각. 배송지 입력이 필요하고 `recipientAddressRegistered=false`이면 유효한 값이며, 배송지 등록 완료 또는 입력 불필요 상태이면 null | | `canceledAt` | `String?` | 취소 UTC 시각. `status=CANCELED`이면 유효한 값 보장 | - `SENT`: 선물을 받는 크리에이터의 프로필이다. - `RECEIVED`: 선물을 보낸 팬의 프로필이다. - 위 계약은 사용자 제공으로 확정됐다. 회원 ID를 이용한 상세 화면이나 프로필 이동은 추가하지 않는다. - 기존 `GET /api/v2/gifts?type=ALL&page=0&size=20`, direction 렌더링, pagination 계약은 유지한다. ### 10.4 외부 의존 계약 상태 | ID | 우선순위 | 제공 필요 계약 | 담당 주체 | 구현 영향 | 재개 조건 | |---|---:|---|---|---|---| | `EXT-001` | P1 | 해결: `counterpartMemberId: Long`, `counterpartNickname: String`, `counterpartProfileImageUrl: String?` | Backend/API, 사용자 계약 제공 | 팬/크리에이터 프로필 이미지·닉네임 표시 | API 계약 제공 완료. 앱 반영은 Phase 6에서 수행하며 구현 완료와 구분한다. | | `EXT-002` | P1 | 부분 해결: `canceledAt` 제공, `sortAt` 미제공 | Backend/API | 취소일 표시는 가능하며 목록 정렬은 계속 서버 응답 순서를 유지 | `canceledAt` 반영은 Phase 8, 별도 정렬 계약은 후속 제공 | | `EXT-003` | P1 | 해결: `recipientAddressRegistered`, `recipientAddressDeadlineAt` 제공 | Backend/API | 배송지 입력 여부와 남은 일수 표시 | Phase 8에서 앱 반영 | ## 11. 상태 표시 매핑 ### 11.1 보낸 선물 카드 | API status | 표시 문구 | |---|---| | `RECEIVED` | `운송장 등록 필요` | | `TRACKING_REGISTERED` | `발송 확인` | | `ARRIVED_AT_MAILBOX` | `사서함 도착` | | `INSPECTION_COMPLETED` | `선물 검수 완료` | | `DELIVERED` | `전달 완료` | | `UNDELIVERABLE` | `전달 불가` | | `CANCELED` | `신청 취소` | ### 11.2 받은 선물 카드 | API status | 메인 문구 | 서브 문구 | |---|---|---| | `TRACKING_REGISTERED` | `recipientAddressRegistered=false`이면 Address 아이템, `true`이면 기존 카드 | Address 아이템은 배송지 입력 안내와 동적 마감 경고 표시 | | `ARRIVED_AT_MAILBOX` | `선물 검수` | `선물 확인 중` | | `INSPECTION_COMPLETED` | `선물 검수 완료` | `배송 중` | | `DELIVERED` | `전달 완료` | 없음 | | `UNDELIVERABLE` | `전달 불가` | 없음 | `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`, `DELIVERED`도 `recipientAddressRegistered=false`이면 Address 아이템을 우선한다. `UNDELIVERABLE`만 배송지 등록 여부와 무관하게 기존 일반 카드를 유지한다. ## 12. 보안과 데이터 취급 - `BuildConfig` 값, token, URL, 신청번호를 불필요하게 log/toast/crash message에 노출하지 않는다. - API 오류 message는 기존 앱 정책대로 사용자 표시 가능한 값만 toast/dialog로 표시한다. - 선물함 목록은 로그인 사용자 기준 개인정보가 포함될 수 있으므로 fixture에는 실제 사용자 정보를 기록하지 않는다. ## 13. 성능과 품질 요구사항 - page size는 20으로 고정한다. - pagination 중 중복 요청을 방지한다. - append 실패 시 기존 목록을 유지한다. - 자동 테스트는 `app/src/test` local unit test로 mapper, formatter, status mapping, request parameter, pagination state를 검증한다. - 날짜 테스트는 고정 현재 시각과 디바이스 타임존을 사용해 UTC 날짜 경계, 남은 일수 올림, 취소일 fallback을 검증한다. - 사용자가 명시적으로 요청하지 않으면 UI/계측 테스트와 스크린샷 QA는 수행하지 않는다. - 마이 탭 진입점의 국가·언어 노출 정책은 `app/src/test` local unit test로 검증하고, 아이콘 크기·간격·constraint는 테스트하지 않는다. ## 14. 성공 기준 ### 14.1 기능 수용 기준 - [x] 진입 시 `type=ALL&page=0&size=20`으로 한 번 조회한다. - [x] `direction=SENT` item은 보낸 선물 카드 UI 모델로 변환된다. - [x] `direction=RECEIVED` item은 받은 선물 카드 UI 모델로 변환된다. - [x] `hasNext=true`일 때 다음 page를 추가 조회한다. - [x] 카드와 배송지 입력 배너 탭 시 item의 `applicationNo`로 상세 이동 event가 발생한다. ### 14.2 UI/UX 수용 기준 - [x] 상단 내비게이션은 고정되고 아래 콘텐츠만 스크롤된다. - [x] `신청 내역`, `선물 내역` 텍스트가 실제 화면에 노출되지 않는다. - [x] 빈 상태가 진입 관점에 맞게 표시된다. - [x] API 실패 시 기존 앱 패턴의 오류와 재시도를 제공한다. ### 14.3 추적성 완료 기준 - [x] 모든 `확정` 요구사항이 `plan-task.md`의 하나 이상의 Goal로 연결된다. - [x] 모든 `외부 의존` 항목에 담당 주체, 영향, 재개 조건이 있다. - [x] API 보강 전 안전한 기본값이 Decision Log에 기록된다. ### 14.4 마이 탭 진입점 수용 기준 - [x] 국가 코드가 `KR`이고 유효 언어가 `ko`일 때만 선물함 항목이 생성된다. - [x] 선물함 항목은 기존 기능 아이콘 목록의 첫 번째에 배치된다. - [x] `ic_my_present` 아이콘과 `선물함` 레이블을 사용한다. - [x] 항목을 누르면 기본 `ALL` 관점의 `GiftInboxActivity`로 이동한다. - [x] 기존 로그인 사용자 전용 기능 아이콘 그리드 정책은 유지된다. ### 14.5 상대방 프로필 수용 기준 - [x] `SENT`의 수신 크리에이터와 `RECEIVED`의 발신 팬 ID·닉네임·이미지 URL이 카드 UI 모델로 전달된다. - [x] 두 카드 프로필 행에 이미지와 API 닉네임이 표시되며 null/blank 이미지에는 `ic_placeholder_profile`을 사용한다. - [x] `SENT` 프로필 아래 `sizeName · categoryName`, `RECEIVED` 상단 프로필·날짜와 본문 상태를 유지한다. - [x] `ALL/0/20` 최초 조회, direction 렌더링, pagination, 카드·배너 상세 이동이 유지된다. - [x] `P6-T1`~`P6-T3`, `P6-GATE` 검증 증거를 기록한다. 기존 완료 기준은 당시 완료 이력으로 유지한다. 검증 근거 (2026-10-01): `plan-task.md`의 P6-GATE 신규 실행에서 focused 테스트와 전체 gift·resource merge·Kotlin compile·ktlint 명령 및 `git diff --check HEAD`가 모두 exit 0이었다. XML 직접 집계는 55개, failures/errors/skipped=0이다. 프로필 표시는 DTO→presenter→모델→adapter→양방향 XML 연결을 대조해 판정했으며 실제 기기·에뮬레이터 표시, 이미지 다운로드, 스크린샷·시각 QA는 수행하지 않았다. ### 14.6 2026-10-06 Figma 회귀 점검 - [x] 받는 사람 목록의 프로필·날짜·상태·서브 문구 구조가 Figma `2531:36237`과 일치한다. - [x] 보내는 사람 목록의 상태·날짜·프로필·사이즈/카테고리 구조가 Figma `2481:19382`와 일치한다. - [x] 배송지 미입력 배너 구조가 Figma `2531:36243`과 일치한다. - [x] 목록 구현에는 수정이 필요한 확정 결함이 없어 기존 코드를 유지한다. ### 14.7 배송지 미입력 아이템 중복 제거 - [x] 받은 선물 상단의 `배송지 입력 기간 안내` 배너는 유지된다. - [x] 배송지 미입력 선물은 일반 받은 카드가 아니라 제목·본문·경고 3문구의 Address 아이템으로 표시된다. - [x] 배송지 미입력 선물이 여러 개면 각 선물마다 Address 아이템이 하나씩 생성되고 각자 자신의 상세로 이동한다. - [x] 같은 배송지 미입력 선물의 Address 아이템과 일반 카드가 동시에 표시되지 않는다. - [x] 목록 API에 `recipientAddressDeadlineAt`이 추가되기 전에는 고정 경고를 유지하고 임의 남은 일수를 계산하지 않는다. ### 14.8 배송지 등록 여부·마감일·취소일 반영 - [x] 목록 DTO가 `recipientAddressRegistered`, `recipientAddressDeadlineAt`, `canceledAt`을 수용한다. - [x] 받은 선물의 `UNDELIVERABLE`은 기존 카드를 유지하고, 그 외 상태는 배송지 등록 여부에 따라 Address 아이템과 기존 카드를 구분한다. - [x] 배송지 미입력 Address 아이템에 마감까지 남은 일수를 24시간 단위 올림으로 표시한다. - [x] `CANCELED` 카드에 `canceledAt ?: createdAt` 기준 `yyyy.MM.dd 취소`를 표시한다. - [x] `v2.gift`의 API UTC 날짜 표시가 디바이스 타임존을 따른다. - [x] 상태 분기, UTC 날짜 경계, 남은 일수, 취소일 fallback local unit test가 통과한다. 검증 근거 (2026-10-08): Phase 8 focused 4개 클래스 55개와 전체 Gift 17개 클래스 211개 local unit test가 failures/errors/skipped 0으로 통과했다. resource merge, Kotlin compile, 변경 파일 lint, diff-check가 성공했으며 최종 Oracle 리뷰는 차단 사항 없이 승인했다. 전역 ktlint 강제 실행은 이번 변경과 무관한 기존 fan-talk test 20건으로 실패했다. 저장소 정책에 따라 기기·에뮬레이터·androidTest·스크린샷 QA는 수행하지 않았다. ## 15. Open Questions | ID | 상태 | 결정 필요 사항 | 현재 권고 | 결정 주체 | 결정 시점 | 영향 Goal | |---|---|---|---|---|---|---| | `OQ-001` | 확정 | `ALL` 진입에서 전체 목록이 비었을 때 보낼/받을 중 어느 empty를 보여줄지 | 크리에이터이면 받은 선물 없음, 일반 회원이면 보낸 선물 신청 내역 없음으로 표시한다. | 사용자 | `2026-10-01` | `P3-T3` | | `OQ-002` | 정정 | 선물 상세 화면이 없을 때 카드 탭 처리 | 후속 상세 구현 완료 후 item의 `applicationNo`로 상세를 연다. | 사용자 | `2026-10-02` | 상세 문서 `P2-T3`, `P7-T5` | | `OQ-003` | 확정 | 받은 선물 하단 `문의하기` 버튼 연결 | 설정 페이지의 카카오 문의하기와 동일한 페이지로 연결한다. | 사용자 | `2026-10-01` | `P3-T5` | | `OQ-004` | 확정 | 마이 탭 진입점 구현에 필요한 레거시 `MyPageFragment` 직접 수정 | 아이콘 목록 생성부와 import만 최소 수정한다. | 사용자 | `2026-10-01` | `P5-T2` | | `OQ-005` | 확정 | 한국어 설정의 판정 기준 | 앱 선택 언어를 우선하고 미선택 시 시스템 언어를 반영하는 `LanguageManager.getEffectiveLanguage`를 사용한다. | 사용자 | `2026-10-01` | `P5-T1` | ## 16. 요구사항 추적표 | 요구사항 범위 | API Contract | 계획 Phase | Goal | 자동 검증 | 수동 검증 | |---|---|---:|---|---|---| | API 조회·pagination | `GET /api/v2/gifts` | 1, 2 | `P1-T1`, `P2-T2`, `P2-T3`, `P2-T4` | `GiftInboxViewModelTest` | 개발자 read-only 대조 | | direction/status mapping | Response item | 1 | `P1-T2` | `GiftInboxPresenterTest` | 개발자 read-only 대조 | | 화면 layout/empty/banner | Figma node IDs | 3 | `P3-T1`~`P3-T5`, `P3-GATE` | mapper/source/resource test | 사용자가 요청한 경우만 수동 QA | | 마이 탭 선물함 진입점 | 국가 코드·유효 언어·기존 기능 아이콘 목록 | 5 | `P5-T1`, `P5-T2`, `P5-GATE` | 진입점 노출 정책 local unit test | 코드·리소스 read-only 대조 | | 상대방 프로필 | Response item 상대방 필드 3개 | 6 | `P6-T1`, `P6-T2`, `P6-T3`, `P6-GATE` | `GiftInboxPresenterTest`, `GiftInboxViewModelTest`, 전체 gift local unit test | XML·adapter read-only 대조 | | 2026-10-06 Figma 회귀 점검 | Figma `2531:36237`, `2481:19382`, `2531:36243` | 6 후속 점검 | 코드 변경 없음 | 기존 gift 회귀 | Figma screenshot·XML·adapter 대조 | | 배송지 미입력 아이템 중복 제거 | 목록 item `status=TRACKING_REGISTERED` | 7 | `P7-R1`, `P7-GATE` | `GiftInboxPresenterTest` | presenter·adapter·기존 Address XML 대조 | | 배송지 등록 여부·마감일·취소일 | 목록 item 신규 3필드, 기존 상세 UTC 날짜 | 8 | `P8-T1`~`P8-T3`, `P8-GATE` | `GiftInboxPresenterTest`, `GiftDetailPresenterTest`, `GiftTrackingPresenterTest` | Figma·presenter·adapter·XML 대조 | ## 17. Decision Log | 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal | |---|---|---|---|---|---| | `2026-10-01` | `DEC-001` | 확정 | 목록 API는 항상 `type=ALL`만 호출한다. | 사용자 요구사항 | `GIFT-INBOX-API-001`, `P1-T1` | | `2026-10-01` | `DEC-002` | 확정 | 취소일/정렬은 API 보강 전 서버 응답 순서를 유지하고 클라이언트 재정렬하지 않는다. | 현재 API에는 `canceledAt`, `sortAt` 없음 | `EXT-002`, `P1-T2` | | `2026-10-01` | `DEC-003` | 확정 | `신청 내역`, `선물 내역` section title은 구현하지 않는다. | 사용자 요구사항이 Figma보다 우선 | `GIFT-INBOX-UI-003`, `P3-GATE` | | `2026-10-01` | `DEC-004` | 확정 | 이번 요청은 PRD와 구현 계획 문서만 생성하고 코드 구현은 하지 않는다. | 사용자 요청 | 전체 | | `2026-10-01` | `DEC-005` | 확정 | `ALL` 전체 빈 목록은 크리에이터이면 받은 선물 없음, 일반 회원이면 보낸 선물 신청 내역 없음으로 표시한다. | 현재 선물은 크리에이터만 받을 수 있음 | `GIFT-INBOX-EMPTY-003`, `P3-T3` | | `2026-10-01` | `DEC-006` | 확정 | 선물 상세 페이지가 없으므로 item 터치 시 상태 표시 문구 toast를 보여준다. | 사용자 보완 요청 | `GIFT-INBOX-UI-005`, `P3-T4` | | `2026-10-01` | `DEC-007` | 확정 | 받은 선물 문의 버튼은 설정 페이지의 카카오 문의하기와 동일한 페이지로 연결한다. | 사용자 보완 요청 | `GIFT-INBOX-INQUIRY-001`, `P3-T5` | | `2026-10-01` | `DEC-008` | 확정 | 마이 탭 선물함 항목은 `countryCode=KR`과 유효 언어 `ko`를 모두 충족할 때만 첫 번째에 표시한다. | 사용자 요구 및 판정 기준 확인 | `GIFT-INBOX-ENTRY-001`, `GIFT-INBOX-ENTRY-002`, `P5-T1`, `P5-T2` | | `2026-10-01` | `DEC-009` | 확정 | 레거시 `MyPageFragment`는 선물함 항목과 클릭 연결을 위해 최소 범위로 직접 수정한다. | 사용자 명시 승인 | `GIFT-INBOX-ENTRY-003`, `P5-T2` | | `2026-10-01` | `DEC-010` | 확정 | 상대방 필드 3개로 두 방향 카드의 이미지·닉네임을 표시하고 null/blank 이미지는 기존 placeholder로 처리한다. 상세 이동과 toast의 충돌은 상세 화면이 없으므로 기존 상태 toast 유지로 확정한다. 조회·direction·pagination은 유지한다. | 사용자 제공 API 계약과 Phase 6 승인, toast 선택 | `EXT-001` 해결, `GIFT-INBOX-PROFILE-001~003`, `P6-T1`~`P6-GATE` | | `2026-10-06` | `DEC-011` | 확정 | 받는 사람·보내는 사람 목록과 배송지 미입력 배너는 제공된 Figma와 현행 adapter/XML 대조에서 수정이 필요한 확정 결함이 없어 유지한다. 상세 이동은 후속 상세 문서의 완료 구현을 따른다. | Figma 3개 노드와 `GiftInboxAdapter`·item XML 대조 | 14.6 회귀 점검 | | `2026-10-06` | `DEC-012` | 정정 | `DEC-006`과 `DEC-010`의 상태 toast 결정을 대체하고, 카드와 배송지 입력 배너는 후속 구현된 `GiftDetailActivity`를 `applicationNo`로 연다. | 상세 화면 구현 완료와 현행 `GiftInboxActivity`·`GiftNavigationTest` 대조 | `GIFT-INBOX-UI-005`, `GIFT-INBOX-BANNER-003`, 상세 문서 `P7-T5` | | `2026-10-06` | `DEC-013` | 정정 | `DEC-011`의 배송지 미입력 배너 유지 결정을 대체한다. 받은 선물 상단의 배송지 입력 기간 안내는 유지하되, 배송지 미입력 선물은 별도 배너와 일반 카드로 중복 표시하지 않고 각 선물 위치의 3문구 Address 아이템으로 표시한다. 현재 목록 API에는 마감일이 없으므로 고정 경고를 유지하고, 향후 아이템별 `recipientAddressDeadlineAt` 제공 시 각 Address 아이템의 경고를 개별 계산한다. | 사용자 요구사항 정정 및 목록 API 계약 확인 | `GIFT-INBOX-UI-002`, `GIFT-INBOX-STATUS-002~003`, `GIFT-INBOX-BANNER-003`, `P7-R1`, `P7-GATE` | | `2026-10-08` | `DEC-014` | 정정 | 배송지 미입력 여부를 status로 추정하지 않고 `recipientAddressRegistered`로 판단한다. 단, `UNDELIVERABLE`은 배송지 여부와 무관하게 기존 카드를 유지한다. | 목록 API 필드 추가 및 사용자 인터뷰 | `GIFT-INBOX-UI-002`, `GIFT-INBOX-STATUS-002`, `P8-T2` | | `2026-10-08` | `DEC-015` | 확정 | 배송지 마감까지 남은 시간을 24시간 단위로 올림해 Figma 문구에 표시한다. 배송지 입력이 필요한 미등록 상태의 null 마감일과 만료된 정상 상태는 발생하지 않으며, 배송지 등록 완료 또는 입력 불필요 상태에서는 마감일이 null이다. | 사용자 인터뷰, Figma `2531:36243` | `GIFT-INBOX-STATUS-003`, `P8-T1`, `P8-T2` | | `2026-10-08` | `DEC-016` | 확정 | `v2.gift`의 API UTC 시각은 디바이스 타임존으로 변환해 표시한다. `CANCELED` 목록 날짜는 `canceledAt`을 사용하고 예외적으로 null이면 `createdAt`을 사용한다. | 사용자 인터뷰, Figma `2481:19434` | `GIFT-INBOX-UI-006`, `GIFT-INBOX-STATUS-004`, `P8-T1`~`P8-T3` | ## 18. 변경 관리 - 요구사항 변경 시 Decision Log에 변경 이유와 날짜를 기록한다. - 관련 요구사항 상태와 수용 기준을 갱신한 뒤 `plan-task.md` 체크리스트를 먼저 수정한다. - 기존 검증 기록과 리뷰 기록은 삭제하거나 덮어쓰지 않는다.