From 7a33586fe61f51cbefbcae4d25e80789887abd92 Mon Sep 17 00:00:00 2001 From: klaus Date: Thu, 1 Oct 2026 21:15:58 +0900 Subject: [PATCH] =?UTF-8?q?docs(gift):=20=EC=84=A0=EB=AC=BC=ED=95=A8=20?= =?UTF-8?q?=EC=9A=94=EA=B5=AC=EC=82=AC=ED=95=AD=EC=9D=84=20=EC=A0=95?= =?UTF-8?q?=EB=A6=AC=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/20261001_선물함_리스트_페이지/prd.md | 371 ++++++++++++++++++++++ 1 file changed, 371 insertions(+) create mode 100644 docs/20261001_선물함_리스트_페이지/prd.md diff --git a/docs/20261001_선물함_리스트_페이지/prd.md b/docs/20261001_선물함_리스트_페이지/prd.md new file mode 100644 index 00000000..9a56d159 --- /dev/null +++ b/docs/20261001_선물함_리스트_페이지/prd.md @@ -0,0 +1,371 @@ +# PRD: 선물함 리스트 페이지 + +## 문서 정보 + +| 항목 | 내용 | +|---|---| +| 문서 상태 | 구현 기준 확정 | +| 작성일 | `2026-10-01` | +| 최종 수정일 | `2026-10-01` | +| 대상 제품 | 선물함 리스트 페이지 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에는 취소일, 배송지 입력 마감일이 없어 Figma 일부 표시값을 완전히 재현할 수 없다. 상대방 프로필은 사용자 제공 API 계약이 확정되어 Phase 6에서 반영한다. + +문제를 해결했다는 판단은 `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 상태 표시 문구를 toast로 보여준다. +- 한국 접속·한국어 유효 언어 조건을 모두 충족하면 마이 탭 기능 아이콘 목록의 첫 번째에 선물함 진입점을 표시한다. + +### 3.2 UX 목표 + +- 상단 뒤로가기 내비게이션은 고정하고, 내비게이션 아래 콘텐츠만 스크롤한다. +- Figma에 보이는 `신청 내역`, `선물 내역` 섹션 타이틀은 실제 화면에 노출하지 않는다. +- 보낸 선물 관점 빈 상태는 안내 배너만 표시하고 별도 empty title/body를 추가하지 않는다. +- 받은 선물 관점 빈 상태는 중앙 empty UI와 `의견 남기기` 버튼을 표시한다. +- 최초 로딩, 실패, 재시도, pagination loading은 기존 앱의 리스트/토스트/로딩 패턴을 재사용한다. + +## 4. Non-Goals + +- `SENT`, `RECEIVED` 별도 목록 API 호출. +- 클라이언트 임의 재정렬. +- 취소일, 배송지 입력 마감일을 추정해서 표시. +- 선물 상세 페이지 신규 구현. 이번 범위는 상세 이동 없이 상태 toast만 포함한다. +- 사용자 승인을 받은 `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 상태 표시 문구를 toast로 보여준다. +9. API 실패 시 기존 toast/dialog 패턴과 재시도 UI를 제공하고 기존 입력/스크롤 상태를 깨지 않는다. + +## 7. 정보 구조와 라우팅 + +```text +GiftInboxActivity + -> Toast(status display text) + -> 설정 페이지의 카카오 문의하기와 동일한 문의 화면 +``` + +- 신규 화면 단위: `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의 상태 표시 문구를 토스트로 보여준다. +- 받은 선물 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`는 받은 선물 카드로 렌더링한다. | 팬 식별 영역, 날짜 라벨, 상태 메인/서브 문구, chevron이 표시된다. | `P1-T2`, `P3-T1` | +| `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` | 확정 | 현재 선물 상세 페이지가 없으므로 item 터치 시 상세 이동 대신 상태 표시 문구를 toast로 보여준다. | 보낸 카드와 받은 카드 터치 모두 item의 상태 문구 toast event를 발생시킨다. | `P3-T4` | + +### 8.3 상태 문구 매핑 + +| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 | +|---|---|---|---|---| +| `GIFT-INBOX-STATUS-001` | 확정 | 보낸 선물 상태 코드를 요구사항 표의 표시 문구로 매핑한다. | `RECEIVED`는 `운송장 등록 필요`, `CANCELED`는 `신청 취소`로 변환된다. | `P1-T2` | +| `GIFT-INBOX-STATUS-002` | 확정 | 받은 선물 상태 코드를 메인/서브 문구로 매핑한다. | `TRACKING_REGISTERED`는 `배송지 입력 필요`/`전달 예정`으로 변환된다. | `P1-T2` | +| `GIFT-INBOX-STATUS-003` | 외부 의존 | 배송지 입력 마감일 기반 `n일 이내` 문구는 API가 `recipientAddressDeadlineAt`을 제공해야 정확히 계산한다. | API 보강 전에는 고정 보조 문구를 쓰지 않거나 Figma 문구의 숫자 없는 버전을 사용한다. | `EXT-003`, `P3-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` | 외부 의존 | 배송지 입력이 필요한 선물이 있으면 파란 안내 배너를 리스트 상단에 표시한다. | `TRACKING_REGISTERED` 받은 선물이 있을 때 첫 대상 상태 문구를 toast로 보여준다. 남은 일수는 API 보강 전 정확히 계산하지 않는다. | `EXT-003`, `P3-T3` | +| `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·상태 toast 동작은 변경하지 않는다. | `ALL/0/20` 최초 조회, 다음 page append 및 카드 클릭 상태 toast 회귀 테스트가 통과한다. 상세 Activity/deeplink는 추가하지 않는다. | `P6-T3`, `P6-GATE` | + +## 9. UI/UX Expectations + +### 9.1 Figma 기준 + +- 보낸 선물, 신청 내역 있음: `2481:19382`. +- 보낸 선물, 신청 내역 없음: `2520:35587`. +- 받은 선물, 받은 선물 없음: `2531:36283`. +- 받은 선물, 받은 선물 있음: `2531:36194`. +- 받은 선물, 상태별 카드 표시: `2531:36237`. +- 사용자 요구사항이 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: 안내 배너, 필요 시 배송지 입력 안내 배너, 카드 리스트, 하단 문의 버튼을 콘텐츠 스크롤 영역에 포함한다. +- 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" + } + ], + "page": 0, + "size": 20, + "hasNext": false + }, + "message": "" +} +``` + +### 10.3 상대방 프로필 계약 + +| 필드 | 타입 | 의미 | +|---|---|---| +| `counterpartMemberId` | `Long` | 상대방 회원 ID | +| `counterpartNickname` | `String` | 상대방 닉네임 | +| `counterpartProfileImageUrl` | `String?` | 상대방 프로필 이미지 URL. null 또는 blank이면 `ic_placeholder_profile` 표시 | + +- `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 | 취소일 표시와 신청/취소 최신순 정렬 | 응답 field와 서버 정렬 계약 제공 | +| `EXT-003` | P1 | `recipientAddressDeadlineAt` | Backend/API | 배송지 입력 남은 일수 계산 | 응답 field와 timezone 정책 제공 | + +## 11. 상태 표시 매핑 + +### 11.1 보낸 선물 카드 + +| API status | 표시 문구 | +|---|---| +| `RECEIVED` | `운송장 등록 필요` | +| `TRACKING_REGISTERED` | `발송 확인` | +| `ARRIVED_AT_MAILBOX` | `사서함 도착` | +| `INSPECTION_COMPLETED` | `선물 검수 완료` | +| `DELIVERED` | `전달 완료` | +| `UNDELIVERABLE` | `전달 불가` | +| `CANCELED` | `신청 취소` | + +### 11.2 받은 선물 카드 + +| API status | 메인 문구 | 서브 문구 | +|---|---|---| +| `TRACKING_REGISTERED` | `배송지 입력 필요` | `전달 예정` | +| `ARRIVED_AT_MAILBOX` | `선물 검수` | `선물 확인 중` | +| `INSPECTION_COMPLETED` | `선물 검수 완료` | `배송 중` | +| `DELIVERED` | `전달 완료` | 없음 | +| `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를 검증한다. +- 사용자가 명시적으로 요청하지 않으면 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 상태 표시 문구 toast 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, 카드 클릭 상태 toast가 유지되며 상세 화면·deeplink는 추가하지 않는다. +- [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는 수행하지 않았다. + +## 15. Open Questions + +| ID | 상태 | 결정 필요 사항 | 현재 권고 | 결정 주체 | 결정 시점 | 영향 Goal | +|---|---|---|---|---|---|---| +| `OQ-001` | 확정 | `ALL` 진입에서 전체 목록이 비었을 때 보낼/받을 중 어느 empty를 보여줄지 | 크리에이터이면 받은 선물 없음, 일반 회원이면 보낸 선물 신청 내역 없음으로 표시한다. | 사용자 | `2026-10-01` | `P3-T3` | +| `OQ-002` | 확정 | 선물 상세 화면이 없을 때 카드 탭 처리 | 상세 이동 대신 item 상태 표시 문구를 toast로 보여준다. | 사용자 | `2026-10-01` | `P3-T4` | +| `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 대조 | + +## 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` | + +## 18. 변경 관리 + +- 요구사항 변경 시 Decision Log에 변경 이유와 날짜를 기록한다. +- 관련 요구사항 상태와 수용 기준을 갱신한 뒤 `plan-task.md` 체크리스트를 먼저 수정한다. +- 기존 검증 기록과 리뷰 기록은 삭제하거나 덮어쓰지 않는다.