Files
sodalive-android/docs/20261029_추천_서브_배너/prd.md
T

6.6 KiB

PRD: 홈·콘텐츠 추천 서브 배너

문서 정보

항목 내용
상태 구현·코드 리뷰 완료, 전체 회귀·실제 화면 QA 제한은 계획에 기록
작성일 2026-10-29
결정권자 사용자
API 기준 사용자 제공 추천 API 통합 계약, 아래 API 계약
구현 계획 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에 기록한다.