feat(widget): 오디오 콘텐츠 카드 컴포넌트를 추가한다

2026-05-19 23:52:53 +09:00
parent 30264935dc
commit 6fda122091
7 changed files with 704 additions and 0 deletions
--- a/docs/plan-task/20260519_오디오콘텐츠카드컴포넌트.md
+++ b/docs/plan-task/20260519_오디오콘텐츠카드컴포넌트.md
@@ -0,0 +1,377 @@
+# 오디오 콘텐츠 카드 컴포넌트 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Figma `20:3800`, `20:3818`, `20:3829` 기준으로 동일 형태와 3개 크기 변형을 갖는 재사용 가능한 Audio Content Card Component를 추가한다.
+
+**Architecture:** XML 레이아웃 `view_audio_content_card.xml`은 썸네일과 label contents의 공통 구조만 제공한다. Kotlin custom view `AudioContentCardView`가 `AudioContentCardSize` size contract를 적용해 카드 폭, 썸네일 크기, label 폭, typography, gap을 변경한다.
+
+**Tech Stack:** Android XML Views, Kotlin custom View, ViewBinding/resource merge, JUnit4 local unit test.
+
+---
+
+## 작업 목표
+- Figma 3개 오디오 콘텐츠 카드 디자인을 Android XML/Kotlin 재사용 컴포넌트로 구현한다.
+- 세 컴포넌트는 구조는 동일하고 크기만 다르므로 하나의 컴포넌트와 size contract로 관리한다.
+- 기존 화면 일괄 적용은 제외하고 컴포넌트 추가로 범위를 제한한다.
+
+## 파일 구조
+- Create: `app/src/main/res/layout/view_audio_content_card.xml`
+  - `AudioContentCardView` 루트, thumbnail `ImageView`, label container, title `TextView`, creator `TextView`를 정의한다.
+- Create: `app/src/main/res/drawable/bg_audio_content_card_thumbnail.xml`
+  - 14dp corner radius thumbnail clipping 배경 또는 outline 기준 리소스를 정의한다. 실제 outline clipping은 custom view에서 처리할 수 있다.
+- Modify: `app/src/main/res/values/dimens.xml`
+  - 필요한 경우 `spacing_2`, `spacing_11` 및 카드 전용 size dimen을 최소 추가한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSize.kt`
+  - `large`, `medium`, `small` size별 dimension/style contract를 정의한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardView.kt`
+  - size 적용, 텍스트 바인딩, 썸네일 view 접근 API를 제공한다.
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSizeTest.kt`
+  - size별 card width, thumbnail size, label width, typography contract를 검증한다.
+- Modify: `docs/plan-task/20260519_오디오콘텐츠카드컴포넌트.md`
+  - 구현 중 체크박스와 검증 기록을 누적한다.
+
+## 구현 계획
+
+### Task 1: 기존 리소스 및 유사 UI 확인
+
+**Files:**
+- Read: `app/src/main/res/values/colors.xml`
+- Read: `app/src/main/res/values/dimens.xml`
+- Read: `app/src/main/res/values/typography.xml`
+- Read: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/CapsuleTabBarView.kt`
+
+- [x] **Step 1: 기존 v2 custom view 패턴 확인**
+
+Run: `rg -n "class .*View @JvmOverloads|setTextAppearance|resources.getDimensionPixelSize" app/src/main/java/kr/co/vividnext/sodalive/v2/widget`
+
+Expected: `CapsuleTabBarView` 등 기존 custom view 구현 스타일을 확인한다.
+
+- [x] **Step 2: 필수 디자인 토큰 확인**
+
+Run: `rg -n "radius_14|spacing_8|gray_500|white|Typography\.Heading4|Typography\.Body1|Typography\.Body5|Typography\.Caption2" app/src/main/res/values`
+
+Expected: radius, color, typography 토큰이 존재함을 확인한다.
+
+- [x] **Step 3: 추가 dimen 필요 여부 확인**
+
+Run: `rg -n "spacing_2|spacing_11|185dp|163dp|151dp|122dp|114dp" app/src/main/res/values app/src/main/res/layout`
+
+Expected: 없는 값은 카드 전용 dimen 또는 직접값 중 하나로 최소 추가한다.
+
+### Task 2: AudioContentCardSize TDD
+
+**Files:**
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSizeTest.kt`
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSize.kt`
+
+- [x] **Step 1: RED - size contract 테스트 추가**
+
+```kotlin
+package kr.co.vividnext.sodalive.v2.widget
+
+import kr.co.vividnext.sodalive.R
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class AudioContentCardSizeTest {
+
+    @Test
+    fun `large size matches figma contract`() {
+        assertEquals(185, AudioContentCardSize.Large.cardWidthDp)
+        assertEquals(185, AudioContentCardSize.Large.thumbnailSizeDp)
+        assertEquals(185, AudioContentCardSize.Large.labelWidthDp)
+        assertEquals(11, AudioContentCardSize.Large.thumbnailLabelGapDp)
+        assertEquals(R.style.Typography_Heading4, AudioContentCardSize.Large.titleStyleRes)
+        assertEquals(R.style.Typography_Body5, AudioContentCardSize.Large.creatorStyleRes)
+    }
+
+    @Test
+    fun `medium size matches figma contract`() {
+        assertEquals(163, AudioContentCardSize.Medium.cardWidthDp)
+        assertEquals(163, AudioContentCardSize.Medium.thumbnailSizeDp)
+        assertEquals(151, AudioContentCardSize.Medium.labelWidthDp)
+        assertEquals(8, AudioContentCardSize.Medium.thumbnailLabelGapDp)
+        assertEquals(R.style.Typography_Heading4, AudioContentCardSize.Medium.titleStyleRes)
+        assertEquals(R.style.Typography_Body5, AudioContentCardSize.Medium.creatorStyleRes)
+    }
+
+    @Test
+    fun `small size matches figma contract`() {
+        assertEquals(122, AudioContentCardSize.Small.cardWidthDp)
+        assertEquals(122, AudioContentCardSize.Small.thumbnailSizeDp)
+        assertEquals(114, AudioContentCardSize.Small.labelWidthDp)
+        assertEquals(8, AudioContentCardSize.Small.thumbnailLabelGapDp)
+        assertEquals(R.style.Typography_Body1, AudioContentCardSize.Small.titleStyleRes)
+        assertEquals(R.style.Typography_Caption2, AudioContentCardSize.Small.creatorStyleRes)
+    }
+}
+```
+
+- [x] **Step 2: RED 실행**
+
+Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.AudioContentCardSizeTest"`
+
+Expected: `Unresolved reference 'AudioContentCardSize'`로 실패한다.
+
+- [x] **Step 3: GREEN - 최소 size contract 추가**
+
+```kotlin
+package kr.co.vividnext.sodalive.v2.widget
+
+import androidx.annotation.StyleRes
+import kr.co.vividnext.sodalive.R
+
+sealed class AudioContentCardSize(
+    val cardWidthDp: Int,
+    val thumbnailSizeDp: Int,
+    val labelWidthDp: Int,
+    val thumbnailLabelGapDp: Int,
+    @StyleRes val titleStyleRes: Int,
+    @StyleRes val creatorStyleRes: Int
+) {
+    data object Large : AudioContentCardSize(
+        cardWidthDp = 185,
+        thumbnailSizeDp = 185,
+        labelWidthDp = 185,
+        thumbnailLabelGapDp = 11,
+        titleStyleRes = R.style.Typography_Heading4,
+        creatorStyleRes = R.style.Typography_Body5
+    )
+
+    data object Medium : AudioContentCardSize(
+        cardWidthDp = 163,
+        thumbnailSizeDp = 163,
+        labelWidthDp = 151,
+        thumbnailLabelGapDp = 8,
+        titleStyleRes = R.style.Typography_Heading4,
+        creatorStyleRes = R.style.Typography_Body5
+    )
+
+    data object Small : AudioContentCardSize(
+        cardWidthDp = 122,
+        thumbnailSizeDp = 122,
+        labelWidthDp = 114,
+        thumbnailLabelGapDp = 8,
+        titleStyleRes = R.style.Typography_Body1,
+        creatorStyleRes = R.style.Typography_Caption2
+    )
+}
+```
+
+- [x] **Step 4: GREEN 실행**
+
+Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.AudioContentCardSizeTest"`
+
+Expected: `BUILD SUCCESSFUL`
+
+### Task 3: Audio content card XML 리소스 추가
+
+**Files:**
+- Create: `app/src/main/res/layout/view_audio_content_card.xml`
+- Create: `app/src/main/res/drawable/bg_audio_content_card_thumbnail.xml`
+- Modify: `app/src/main/res/values/dimens.xml` if needed
+
+- [x] **Step 1: thumbnail radius drawable 추가**
+
+`app/src/main/res/drawable/bg_audio_content_card_thumbnail.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<shape xmlns:android="http://schemas.android.com/apk/res/android">
+    <solid android:color="@color/gray_900" />
+    <corners android:radius="@dimen/radius_14" />
+</shape>
+```
+
+- [x] **Step 2: audio content card layout 추가**
+
+`app/src/main/res/layout/view_audio_content_card.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<kr.co.vividnext.sodalive.v2.widget.AudioContentCardView xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:orientation="vertical">
+
+    <ImageView
+        android:id="@+id/iv_audio_content_thumbnail"
+        android:layout_width="0dp"
+        android:layout_height="0dp"
+        android:background="@drawable/bg_audio_content_card_thumbnail"
+        android:clipToOutline="true"
+        android:contentDescription="@null"
+        android:scaleType="centerCrop" />
+
+    <LinearLayout
+        android:id="@+id/ll_audio_content_label"
+        android:layout_width="0dp"
+        android:layout_height="wrap_content"
+        android:orientation="vertical">
+
+        <TextView
+            android:id="@+id/tv_audio_content_title"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:ellipsize="end"
+            android:maxLines="1"
+            android:textColor="@color/white"
+            tools:text="콘텐츠 제목" />
+
+        <TextView
+            android:id="@+id/tv_audio_content_creator"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:ellipsize="end"
+            android:maxLines="1"
+            android:textColor="@color/gray_500"
+            tools:text="크리에이터 이름" />
+    </LinearLayout>
+</kr.co.vividnext.sodalive.v2.widget.AudioContentCardView>
+```
+
+- [x] **Step 3: 추가 dimen 최소화**
+
+필요한 dimension은 `AudioContentCardSize`의 dp contract에서 변환해 적용한다. XML에서 직접 필요한 값이 생길 때만 `dimens.xml`에 최소 추가한다.
+
+### Task 4: AudioContentCardView 구현
+
+**Files:**
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardView.kt`
+
+- [x] **Step 1: custom view 추가**
+
+`AudioContentCardView`는 `LinearLayout`을 상속하고 `@JvmOverloads constructor` 패턴을 따른다.
+
+Required API:
+- `fun setSize(size: AudioContentCardSize)`
+- `fun setContent(title: String, creatorName: String)`
+- `fun thumbnailView(): ImageView`
+
+Implementation requirements:
+- 기본 size는 `AudioContentCardSize.Medium`을 사용한다.
+- `orientation = VERTICAL`을 보장한다.
+- root layout width를 size별 `cardWidthDp`로 적용한다.
+- thumbnail width/height를 size별 `thumbnailSizeDp`로 적용한다.
+- label container width를 size별 `labelWidthDp`로 적용한다.
+- label top margin을 size별 `thumbnailLabelGapDp`로 적용한다.
+- title/creator typography는 size별 style resource를 적용한다.
+- title과 creator 사이 gap은 2dp로 적용한다.
+- thumbnail radius clipping은 `ViewOutlineProvider` 또는 기존 프로젝트에서 사용하는 방식으로 14dp radius를 보장한다.
+
+- [x] **Step 2: 텍스트 바인딩 구현**
+
+`setContent(title, creatorName)`은 title TextView와 creator TextView에 값을 그대로 바인딩한다. 빈 문자열 보정은 호출부 책임으로 둔다.
+
+- [x] **Step 3: 썸네일 바인딩 확장 지점 제공**
+
+이미지 로딩 라이브러리를 컴포넌트 내부에 고정하지 않도록 `thumbnailView()`로 `ImageView`를 노출한다.
+
+### Task 5: 검증 및 문서 기록
+
+**Files:**
+- Modify: `docs/plan-task/20260519_오디오콘텐츠카드컴포넌트.md`
+
+- [x] **Step 1: 단일 테스트 실행**
+
+Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.AudioContentCardSizeTest"`
+
+Expected: `BUILD SUCCESSFUL`
+
+- [x] **Step 2: LSP 진단 실행**
+
+Run: `lsp_diagnostics` on modified Kotlin/XML files
+
+Expected: 새 오류가 없다. XML LSP가 환경에 없으면 그 사실을 검증 기록에 남긴다.
+
+- [x] **Step 3: 디버그 빌드 실행**
+
+Run: `./gradlew :app:assembleDebug`
+
+Expected: `BUILD SUCCESSFUL`
+
+- [x] **Step 4: ViewBinding 생성 확인**
+
+Run: `rg --files app/build/generated/data_binding_base_class_source_out/debug/out | rg "ViewAudioContentCardBinding"`
+
+Expected: `ViewAudioContentCardBinding` 생성 파일이 출력된다.
+
+- [x] **Step 5: 검증 기록 누적**
+
+문서 하단 `검증 기록`에 실행한 명령, 결과, 빌드 성공 여부를 한국어로 기록한다.
+
+## 체크리스트
+- [x] AC1: `large` 카드는 width `185dp`, thumbnail `185dp x 185dp`, label width `185dp`를 사용한다.
+  - QA: `AudioContentCardSizeTest`, custom view size 적용 확인
+- [x] AC2: `medium` 카드는 width `163dp`, thumbnail `163dp x 163dp`, label width `151dp`를 사용한다.
+  - QA: `AudioContentCardSizeTest`, custom view size 적용 확인
+- [x] AC3: `small` 카드는 width `122dp`, thumbnail `122dp x 122dp`, label width `114dp`를 사용한다.
+  - QA: `AudioContentCardSizeTest`, custom view size 적용 확인
+- [x] AC4: 모든 thumbnail은 radius `14dp`, `centerCrop`을 사용한다.
+  - QA: drawable/custom view clipping, XML `scaleType` 확인
+- [x] AC5: title은 white, creator name은 `gray_500`이며 둘 다 한 줄 말줄임 처리된다.
+  - QA: XML `textColor`, `maxLines`, `ellipsize` 확인
+- [x] AC6: size별 typography는 large/medium title `Typography.Heading4`, creator `Typography.Body5`, small title `Typography.Body1`, creator `Typography.Caption2`를 사용한다.
+  - QA: `AudioContentCardSizeTest`, custom view style 적용 확인
+- [x] AC7: 이미지 로딩 라이브러리를 컴포넌트 내부에 고정하지 않는다.
+  - QA: `thumbnailView()` API 및 의존성 변경 없음 확인
+- [x] AC8: 기존 화면 파일은 변경하지 않는다.
+  - QA: `git status --short` 변경 파일 확인
+- [x] AC9: 리소스 병합 및 디버그 빌드가 성공한다.
+  - QA: `./gradlew :app:assembleDebug`
+
+## 검증 기록
+- 2026-05-19
+  - 무엇/왜/어떻게: 사용자 요청에 따라 구현 전 PRD와 구현 계획/TASK 문서만 작성했다. Figma `20:3800`, `20:3818`, `20:3829`는 동일 구조의 audio 콘텐츠 카드 크기 변형으로 문서화했다.
+  - 실행 명령/도구:
+    - `Figma_get_design_context(20:3800)`
+    - `Figma_get_design_context(20:3818)`
+    - `Figma_get_design_context(20:3829)`
+    - `Figma_get_screenshot(20:3800)`
+    - `Figma_get_screenshot(20:3818)`
+    - `Figma_get_screenshot(20:3829)`
+    - `read(docs/agent-guides/workflow-docs-commits.md)`
+    - `read(docs/prd/sample-prd.md)`
+    - `read(docs/prd/20260519_섹션타이틀컴포넌트_prd.md)`
+    - `read(docs/plan-task/20260519_섹션타이틀컴포넌트.md)`
+    - `read(docs/prd/20260519_캡슐탭바컴포넌트_prd.md)`
+    - `read(docs/plan-task/20260519_캡슐탭바컴포넌트.md)`
+    - `read(app/src/main/res/values/colors.xml)`
+    - `read(app/src/main/res/values/dimens.xml)`
+    - `read(app/src/main/res/values/typography.xml)`
+    - `read(app/src/main/java/kr/co/vividnext/sodalive/v2/widget/CapsuleTabBarView.kt)`
+    - `read(app/src/main/java/kr/co/vividnext/sodalive/v2/widget/CapsuleTabSelectionState.kt)`
+  - 결과:
+    - PRD 문서는 `docs/prd/20260519_오디오콘텐츠카드컴포넌트_prd.md`에 작성했다.
+    - 계획/TASK 문서는 `docs/plan-task/20260519_오디오콘텐츠카드컴포넌트.md`에 작성했다.
+    - Figma 3개 노드는 `large`, `medium`, `small` size variant로 정리했다.
+    - 코드, 리소스, 레이아웃 구현 파일은 변경하지 않았다.
+    - 실제 구현과 빌드 검증은 사용자 승인 후 계획 문서 체크리스트에 따라 진행한다.
+- 2026-05-19
+  - 무엇/왜/어떻게: 계획 문서에 따라 오디오 콘텐츠 카드 컴포넌트를 구현했다. `AudioContentCardSize`로 size contract를 분리하고, `AudioContentCardView`에서 카드 폭/썸네일/label/typography/gap을 size별로 적용하도록 했다.
+  - 실행 명령/도구:
+    - `rg -n "class .*View @JvmOverloads|setTextAppearance|resources.getDimensionPixelSize" app/src/main/java/kr/co/vividnext/sodalive/v2/widget`
+    - `rg -n "radius_14|spacing_8|gray_500|white|Typography\.Heading4|Typography\.Body1|Typography\.Body5|Typography\.Caption2" app/src/main/res/values`
+    - `rg -n "spacing_2|spacing_11|185dp|163dp|151dp|122dp|114dp" app/src/main/res/values app/src/main/res/layout`
+    - `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.AudioContentCardSizeTest"` (RED)
+    - `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.AudioContentCardSizeTest"` (GREEN)
+    - `lsp_diagnostics` on modified Kotlin/XML files
+    - `rg -n "AudioContentCardView|iv_audio_content_thumbnail|clipToOutline=\"true\"|scaleType=\"centerCrop\"|tv_audio_content_title|tv_audio_content_creator|gray_500|bg_audio_content_card_thumbnail" app/src/main/res/layout/view_audio_content_card.xml app/src/main/res/drawable/bg_audio_content_card_thumbnail.xml`
+    - `rg -n "fun setSize|fun setContent|fun thumbnailView|AudioContentCardSize\.Medium|TITLE_CREATOR_GAP_DP|setTextAppearance" app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardView.kt app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSize.kt`
+    - `./gradlew :app:assembleDebug`
+    - `rg --files app/build/generated/data_binding_base_class_source_out/debug/out | rg "ViewAudioContentCardBinding"`
+    - `git status --short`
+  - 결과:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSize.kt`를 추가했다.
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardView.kt`를 추가했다.
+    - `app/src/main/res/layout/view_audio_content_card.xml`을 추가했다.
+    - `app/src/main/res/drawable/bg_audio_content_card_thumbnail.xml`을 추가했다.
+    - `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/AudioContentCardSizeTest.kt`를 추가했다.
+    - RED 실행은 `Unresolved reference 'AudioContentCardSize'`로 실패해 테스트가 신규 contract 부재를 검증함을 확인했다.
+    - GREEN 실행은 `BUILD SUCCESSFUL`로 완료됐다.
+    - 현재 환경에는 Kotlin/XML LSP 서버가 설정되어 있지 않아 `lsp_diagnostics`는 실행 불가했다.
+    - XML 속성 확인에서 `clipToOutline`, `centerCrop`, title/creator id, `gray_500`, thumbnail drawable 참조를 확인했다.
+    - `:app:assembleDebug`는 `BUILD SUCCESSFUL`로 완료됐다.
+    - `ViewAudioContentCardBinding.java` 생성 파일을 확인해 ViewBinding 생성 가능성을 확인했다.