diff --git a/docs/20261029_추천_서브_배너/prd.md b/docs/20261029_추천_서브_배너/prd.md new file mode 100644 index 00000000..8f81ad71 --- /dev/null +++ b/docs/20261029_추천_서브_배너/prd.md @@ -0,0 +1,82 @@ +# PRD: 홈·콘텐츠 추천 서브 배너 + +## 문서 정보 + +| 항목 | 내용 | +|---|---| +| 상태 | 구현·코드 리뷰 완료, 전체 회귀·실제 화면 QA 제한은 계획에 기록 | +| 작성일 | 2026-10-29 | +| 결정권자 | 사용자 | +| API 기준 | 사용자 제공 추천 API 통합 계약, 아래 API 계약 | +| 구현 계획 | [plan-task.md](plan-task.md) | + +## 목표와 범위 + +홈 추천 및 콘텐츠 추천에서 기존 추천 조회 결과의 모든 표시 대상 서브 배너를 가로 캐러셀로 제공한다. 기존 추천 콘텐츠와 메인 배너는 보존한다. Android XML Views 및 기존 이미지 로딩·상태 처리 관례를 사용하며 신규 의존성을 추가하지 않는다. + +별도 배너 endpoint, placement query, 기기 시각 기반 기간 필터, 로컬 노출 예약, iOS 구현, 신규 로그인 흐름, 운영 요청의 fixture 자동 대체는 범위 밖이다. worktree 없이 현재 작업 디렉터리에서 진행한다. + +## 확정 요구사항 + +| ID | 요구사항 | 수용 기준 | +|---|---|---| +| SB-01 | 두 추천 GET의 기존 data에 subBanners를 추가 소비 | 기존 필드와 banners 유지, 배너 추가 요청 0회 | +| SB-02 | 비로그인 조회 허용 | 비로그인 Authorization 없음, 로그인 헤더 기존 값 유지, 조회 로그인 차단 없음 | +| SB-03 | placement 및 Android 링크 필터 | 홈/콘텐츠 격리, Android 또는 웹 유효 URL 존재, iOS 단독 제외, 응답 순서 및 전체 대상 유지 | +| SB-04 | 홈 배치 | 방금 활동한 크리에이터 아래, 최근 데뷔 크리에이터 위 | +| SB-05 | 콘텐츠 배치 | 최상단 메인 배너 아래, 오직 소다라이브에서만 섹션 위 | +| SB-06 | 크기 및 간격 | 좌우 padding 없이 전체 너비, 현재 이미지 원본 비율에 따른 가변 높이, 자르기/늘리기 없음, 기존 섹션 간격 48dp | +| SB-07 | 캐러셀 | 복수 항목 5초 자동 전환 및 수동 스와이프, 단일 항목 자동 전환 없음, 화면 수명주기 정지 시 타이머 중지 | +| SB-08 | 빈 목록 | 필터 결과 없음이면 컴포넌트 및 추가 간격 없음, 기존 섹션 간격 유지 | +| SB-09 | 탭 실행 | Android 딥링크 우선, 없거나 실행 실패 시 유효 웹 링크 최대 한 번, iOS 링크 실행 금지, 모두 실패해도 추천 콘텐츠 유지 | +| SB-10 | 외부 입력 검증 | 웹/이미지는 절대 http(s) 및 host 필수, 딥링크는 절대 URI, javascript/data/file/content scheme 대소문자 무관 거부, URI 원문 보존 | +| SB-11 | 오류 구분 | HTTP 오류 및 success:false는 기존 추천 오류 처리, 정상 빈 배열과 구별, 개별 이미지/링크 실패는 다른 추천 콘텐츠와 격리 | +| SB-12 | ID와 기간 | 정수 ID는 부동소수점 변환 없이 보존, 날짜 필드 추가 및 기기 시계 판정 없음 | + +## API 계약 + +`GET /api/v2/home/recommendations` 및 `GET /api/v2/audio/recommendations`를 기존 클라이언트로 사용한다. 성공은 HTTP 200 및 `success:true`이며 응답 envelope는 `success`, `message`, `data`, `errorProperty`다. 기존 공통 envelope가 사용하지 않는 오류 필드를 무시하는 동작은 유지하며 레거시 모델은 변경하지 않는다. + +`data.subBanners`는 배열이고 결과가 없으면 `[]`다. 홈 placement는 `HOME_RECOMMENDATION`, 콘텐츠 placement는 `CONTENT_RECOMMENDATION`이다. 서버가 활성/기간 조건을 만족하는 모든 항목을 ID 오름차순으로 제공한다. 클라이언트는 재정렬하지 않는다. + +| 필드 | 계약 | +|---|---| +| id | JSON 정수, Kotlin 정수 정밀도 전략 적용 | +| placement | HOME_RECOMMENDATION 또는 CONTENT_RECOMMENDATION | +| imageUrl | 절대 http/https URL | +| webUrl | string 또는 null | +| androidDeepLink | string 또는 null | +| iosDeepLink | string 또는 null, Android 실행 대상 아님 | + +공개 DTO에 startDate/endDate/isActive나 서버가 제공하지 않는 크기 필드를 추가하지 않는다. 이미지 크기는 로딩 결과에서 얻는다. 설치 앱 사전 조회로 표시 대상을 줄이지 않는다. URI를 trim/normalize/re-encode하여 실행하지 않는다. + +## UI와 오류 정책 + +- 기존 섹션 사이의 `spacing_48`을 재사용한다. 새 배너가 숨겨지면 그 배너가 추가한 간격만 제거한다. +- 이미지 비율이 달라지면 현재 슬라이드의 높이도 달라지고 아래 콘텐츠가 이동한다. 사용자가 승인한 동작이다. +- 기존 배너의 350ms 전환 관례를 가능한 범위에서 재사용하되 기존 정사각형 배너 컴포넌트의 동작을 변경하지 않는다. +- 불필요한 제목, CTA, indicator, placeholder, 이미지 실패 전용 화면을 추가하지 않는다. 이미지 로딩 실패가 추천 응답 자체를 실패로 바꾸지 않는다. +- 클릭 실패는 기존 일반 오류 피드백을 활용하며 URL·토큰을 로그나 사용자 메시지에 노출하지 않는다. + +## 검증 시나리오 + +| 시나리오 | 이진 통과 조건 | 증거 | +|---|---|---| +| S1 조회·매핑 | 두 GET에서 익명 헤더 없음/로그인 헤더 보존, 다중 항목 순서 및 placement 격리, 배너 단독 응답도 Content | Retrofit/로컬 테스트 및 실제 화면 | +| S2 캐러셀 | 5초 전환, 단일/빈 목록 및 lifecycle 정지, 선택 이미지 비율 반영, 빈 배너 추가 gap 없음 | 상태/콜백 로컬 테스트 및 화면 확인 | +| S3 링크 | 8가지 링크 조합, URI 원문 보존, 금지 scheme 거부, Android 우선·웹 최대 한 번·양쪽 실패 격리 | 정책/opener 로컬 테스트 | +| S4 오류·회귀 | HTTP 오류 및 success:false와 [] 구분, 기존 추천/메인 배너 유지, 이미지 실패 격리 | 기존/신규 테스트, 전체 local suite, build | + +자동 테스트는 `app/src/test`의 입력/출력 로직을 대상으로 하고 레이아웃 속성 assertion이나 계측 테스트를 추가하지 않는다. 실기기 QA는 사용자의 ultrawork 검증 요청 범위에서 수행 가능 여부를 확인하되 사용자 앱 데이터·로그인 상태를 삭제하지 않는다. 실행 불가능한 진단/QA는 완료로 표시하지 않는다. + +## Decision Log + +| 날짜 | 결정 | 근거 | +|---|---|---| +| 2026-10-29 | 지정 위치, 전체 너비, 원본 비율 | 최초 사용자 요청 | +| 2026-10-29 | 5초 전환, 현재 이미지별 가변 높이, 빈 컴포넌트 숨김, worktree 미사용 | 후속 사용자 확정 | +| 2026-10-29 | 48dp 간격 및 기존 추천 오류 흐름 유지 | 두 화면 XML과 ViewModel 조사 | + +## 열린 질문 + +제품 동작의 중요한 미결 사항 없음. 검증 환경 및 실행 증거는 계획의 Verification Log에 기록한다.