klaus/sodalive-android
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
0c8c9f9b5f1e670889b593d4aac20c1ca36b9ece
sodalive-android/docs/prd/20260527_배너컴포넌트_prd.md

12 KiB
Raw Blame History

PRD: 배너 컴포넌트

1. Overview

Figma 24:5525 디자인을 기준으로 이미지 배너를 자동 전환, 수동 스와이프, 카운터 오버레이, 터치 콜백과 함께 제공하는 Android XML Views 기반 재사용 컴포넌트를 개발한다.

2. Problem

  • 여러 화면에서 이미지 배너를 사용할 때 자동 전환 주기, 전환 시간, 카운터 표기, 무한 순환 동작이 화면별로 달라질 수 있다.
  • 배너 터치 동작은 화면마다 달라질 수 있으므로 UI 컴포넌트가 이동 목적지나 액션 타입을 직접 알면 재사용성이 낮아진다.
  • XML 레이아웃에서 배너를 배치할 때 런타임 데이터가 없어도 레이아웃 에디터에서 크기와 기본 형태를 미리 확인할 수 있어야 한다.
  • 기존 배너 구현은 특정 화면과 외부 라이브러리 사용 방식에 묶여 있어 신규 v2 공용 컴포넌트 계약으로 바로 재사용하기 어렵다.

3. Goals

  • kr.co.vividnext.sodalive.v2.widget.banner 하위에 신규 공용 배너 컴포넌트를 정의한다.
  • Figma 24:5525 기준의 이미지 카드, 14dp radius, 우상단 01 / 20 형태의 카운터 오버레이를 제공한다.
  • 배너 아이템은 1:1 비율로 표시하고, 아이템 width는 화면 width에서 좌우 여백 20dp씩을 제외한 값으로 계산한다.
  • 배너가 여러 개일 때 아이템 사이 간격은 8dp이며, 현재 배너 좌우 빈 공간에는 이전/다음 배너가 약간 보여야 한다.
  • 배너 목록이 2개 이상이면 5초마다 자동으로 다음 배너로 전환한다.
  • 배너 전환 애니메이션 시간은 350ms를 기준으로 한다.
  • 마지막 배너에서 동일한 방향으로 스와이프하면 첫 번째 배너가 보이는 무한 순환 동작을 제공한다.
  • 사용자가 직접 스와이프하면 자동 전환 타이머를 초기화한다.
  • 호출부는 배너 아이템별 터치 액션을 콜백으로 연결할 수 있어야 한다.
  • XML에서 배치할 때 디자인 타임 미리보기가 가능해야 한다.

4. Non-Goals

  • 이번 범위에서는 서버 API, DTO, 딥링크 스키마, 이벤트 추적 스키마를 정의하지 않는다.
  • 기존 화면의 배너를 신규 컴포넌트로 일괄 교체하지 않는다.
  • Compose 컴포넌트 또는 Compose Theme를 추가하지 않는다.
  • Yandex 광고 배너와 같은 광고 SDK 배너는 이번 컴포넌트 범위에 포함하지 않는다.
  • 기존 com.zhpan.bannerview.BannerViewPager 래핑 가능성은 검토하지 않는다.
  • Figma에 없는 제목, 설명, CTA 버튼, 페이지 dot indicator, skeleton loading, shimmer, 별도 pressed animation은 추가하지 않는다.

5. Target Users

  • 앱 내 배너를 확인하고 터치하는 사용자.
  • XML 레이아웃에서 재사용 가능한 배너 UI를 배치하고 데이터와 클릭 동작을 연결하는 Android 개발자.

6. User Stories

  • 사용자는 여러 개의 배너를 자동 전환과 스와이프로 자연스럽게 탐색하고 싶다.
  • 사용자는 마지막 배너 이후에도 같은 방향 스와이프로 첫 번째 배너를 이어서 볼 수 있기를 기대한다.
  • 사용자는 현재 보고 있는 배너가 전체 중 몇 번째인지 우상단 카운터로 확인하고 싶다.
  • 개발자는 화면별 이동 정책을 컴포넌트 밖에서 콜백으로 연결하고 싶다.
  • 개발자는 XML 작성 시 실제 데이터가 없어도 배너의 크기와 형태를 미리 확인하고 싶다.

7. Core Features

Banner Component

Figma 24:5525 기준의 이미지 배너를 XML + Kotlin custom view 기반 공용 컴포넌트로 제공한다.

Figma Reference

Visual Requirements

  • 기본 배너 비율은 1:1 정사각형이다.
  • 기본 배너 item width는 screenWidth - 40dp로 계산한다.
  • 배너 item height는 계산된 item width와 동일하게 적용한다.
  • 현재 배너 item은 부모 영역의 가로 가운데에 정렬한다.
  • 현재 배너 item은 화면 왼쪽에서 20dp, 오른쪽에서 20dp 떨어진 위치를 기준으로 표시한다.
  • 배너가 여러 개이면 item 사이 간격은 8dp다.
  • 배너가 여러 개이면 현재 배너 좌우 빈 공간에 이전/다음 배너 일부가 보여야 한다.
  • 배너 이미지는 전체 영역을 채우며 centerCrop 기준으로 표시한다.
  • 배너 root와 이미지 영역은 radius_14 또는 14dp radius를 적용한다.
  • 카운터는 배너 우상단에 배치한다.
  • 카운터 위치는 상단 14dp, 오른쪽 14dp를 기준으로 한다.
  • 카운터 배경은 rgba(0,0,0,0.7)에 가까운 반투명 검정, capsule radius를 적용한다.
  • 카운터 내부 padding은 horizontal 6dp, vertical 4dp를 기준으로 한다.
  • 카운터 텍스트는 Pretendard Medium, 14sp, line-height 1.45를 기준으로 한다.
  • 현재 index는 white, 구분자 /와 전체 count는 gray_400 계열 색상을 사용한다.
  • 현재 index와 전체 count는 두 자리 형식으로 표시한다. 예: 01 / 20.

Behavior Requirements

  • 배너 목록이 0개이면 컴포넌트 영역은 표시하지 않는다.
  • 배너 목록이 1개이면 자동 전환, 수동 스와이프, 카운터를 사용하지 않고 단일 이미지만 표시한다.
  • 배너 목록이 1개이면 좌우 peek 영역 없이 단일 배너를 가운데 정렬한다.
  • 배너 목록이 2개 이상이면 카운터를 표시하고 자동 전환을 시작한다.
  • 배너 목록이 2개 이상이면 이전/다음 배너가 좌우에 일부 보이는 상태를 유지한다.
  • 자동 전환 주기는 5초다.
  • 전환 애니메이션 시간은 350ms다.
  • 자동 전환 방향은 다음 배너 방향으로 고정한다.
  • 마지막 배너 자동 전환 후에는 첫 번째 배너가 표시되어야 한다.
  • 마지막 배너에서 사용자가 다음 방향으로 스와이프하면 첫 번째 배너가 표시되어야 한다.
  • 첫 번째 배너에서 사용자가 이전 방향으로 스와이프하면 마지막 배너가 표시되어야 한다.
  • 사용자가 직접 스와이프하면 현재 시점부터 자동 전환 타이머를 다시 5초로 초기화한다.
  • 컴포넌트가 화면에서 detach되거나 lifecycle이 정지되면 자동 전환 타이머가 중지되어야 한다.
  • 컴포넌트가 다시 표시되고 배너 목록이 2개 이상이면 자동 전환 타이머를 재개할 수 있어야 한다.

Data Contract Requirements

  • 배너 컴포넌트 전용 UI 모델을 정의한다.
  • 최소 데이터는 다음 정보를 포함한다.
    • bannerId: 호출부에서 식별에 사용할 수 있는 선택적 id.
    • imageUrl: 배너 이미지 URL.
  • 서버 응답 DTO, 딥링크 타입, 콘텐츠 상세 타입, 외부 URL 타입은 배너 컴포넌트 모델에 포함하지 않는다.
  • 배너 터치 시 컴포넌트는 현재 배너 UI 모델을 호출부 콜백으로 전달한다.
  • 이미지 로딩 실패, placeholder, retry 정책은 호출 화면 또는 이미지 로딩 계층 정책을 따른다.

XML Preview Requirements

  • XML layout editor에서 배너 컴포넌트의 기본 형태를 미리 볼 수 있어야 한다.
  • 디자인 타임에는 샘플 이미지 또는 placeholder 배경과 샘플 카운터가 표시되어야 한다.
  • tools: 속성 또는 커스텀 preview 속성으로 샘플 count와 current index를 확인할 수 있어야 한다.
  • 런타임 데이터가 없어도 XML 미리보기에서 배너 높이, radius, 카운터 위치가 확인되어야 한다.

Edge Cases

  • imageUrl이 비어 있으면 호출부 이미지 로딩 정책에 따라 placeholder 또는 빈 이미지로 표시한다.
  • 배너 목록 갱신 시 현재 index가 새 목록 범위를 벗어나면 첫 번째 배너로 보정한다.
  • 배너 목록 갱신 후 0개가 되면 컴포넌트 영역을 숨기고 자동 전환 타이머를 중지한다.
  • 배너 목록 갱신 후 1개가 되면 첫 번째 이미지만 표시하고 자동 전환 타이머를 중지한다.
  • 배너 목록 갱신 후 2개 이상이 되면 첫 번째 배너 기준으로 카운터와 자동 전환을 다시 시작한다.
  • 빠른 연속 스와이프 중에도 카운터는 실제 표시 중인 배너 index와 일치해야 한다.
  • 터치 콜백이 등록되지 않은 경우 배너 터치가 앱을 크래시시키지 않아야 한다.

8. UX / UI Expectations

  • 배너는 이미지 중심 컴포넌트이며 텍스트 정보는 카운터만 표시한다.
  • 배너 radius와 카운터 위치는 Figma와 일관되게 유지한다.
  • 배너는 화면 좌우 20dp 여백을 기준으로 가운데 정렬되고, 정사각형 비율을 유지해야 한다.
  • 여러 배너를 표시할 때는 8dp 간격과 좌우 peek 노출로 다음/이전 콘텐츠가 있음을 사용자가 알 수 있어야 한다.
  • 카운터는 이미지 위에서 읽히되 배너 콘텐츠를 과도하게 가리지 않아야 한다.
  • 자동 전환은 사용자의 수동 스와이프보다 우선하지 않아야 하며, 사용자가 조작한 직후에는 타이머가 초기화되어야 한다.
  • 무한 순환은 사용자가 끝에 도달했다는 끊김 없이 자연스럽게 동작해야 한다.
  • 배너 터치 가능 여부는 호출부 콜백 등록 여부와 화면 정책을 따른다.

9. Technical Constraints

  • 현재 프로젝트는 Android XML Views + Kotlin custom View + ViewBinding/resource 기반이므로 XML layout과 Kotlin custom view 패턴을 우선한다.
  • 신규 Kotlin 코드는 app/src/main/java/kr/co/vividnext/sodalive/v2/widget/banner 하위 패키지에 작성한다.
  • 색상, spacing, radius, typography는 기존 colors.xml, dimens.xml, typography.xml token을 우선 재사용한다.
  • 기존 BannerViewPager 래핑 없이 신규 컴포넌트 자체 구현으로 진행한다.
  • 이미지 로딩 라이브러리를 컴포넌트 내부에 고정하지 않고, 호출부가 이미지 로딩을 연결할 수 있는 ImageView 접근 또는 바인딩 계약을 제공한다.
  • 자동 전환 타이머는 view lifecycle에 맞춰 누수 없이 시작/중지되어야 한다.
  • 기존 화면 파일은 요청 없이 변경하지 않는다.

10. Metrics

  • Figma 24:5525 기준의 14dp radius와 우상단 카운터가 구현된다.
  • 배너 item은 1:1 비율이며 width와 height가 screenWidth - 40dp로 계산된다.
  • 현재 배너는 가운데 정렬되고 화면 좌우에 각각 20dp 기준 여백을 가진다.
  • 배너 목록 2개 이상에서는 item 간격 8dp와 좌우 이전/다음 배너 일부 노출이 적용된다.
  • 배너 목록 0개에서는 컴포넌트 영역이 숨겨진다.
  • 배너 목록 1개에서는 단일 이미지만 표시되고 자동 전환, 스와이프, 카운터가 비활성화된다.
  • 배너 목록 2개 이상에서는 5초 자동 전환과 350ms 전환 애니메이션이 동작한다.
  • 마지막 배너 다음에는 첫 번째 배너가 표시되고, 첫 번째 배너 이전에는 마지막 배너가 표시된다.
  • 수동 스와이프 후 자동 전환 타이머가 5초로 초기화된다.
  • 배너 터치 시 호출부 콜백으로 현재 배너 아이템이 전달된다.
  • XML layout editor에서 배너 기본 형태와 샘플 카운터를 미리 볼 수 있다.
  • 관련 unit test 또는 Robolectric/view 로직 테스트와 Android resource merge/build가 성공한다.

11. Open Questions

  • 사용자 요청이 “PRD 문서 작성”이므로 이번 작업에서는 구현 파일과 계획/TASK 문서를 만들지 않는다.
  • 실제 이미지 placeholder 리소스는 구현 계획 단계에서 기존 리소스 재사용 여부를 확인해 결정한다.