docs(subbanner): 추천 서브 배너 요구사항을 기록한다
This commit is contained in:
@@ -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에 기록한다.
|
||||
Reference in New Issue
Block a user