docs(content): 콘텐츠 랭킹 탭 계획을 추가한다

2026-06-24 13:34:44 +09:00
parent 6590cf8300
commit 37b70a956c
2 changed files with 908 additions and 0 deletions
--- a/docs/20260623_메인_콘텐츠_탭_내부_랭킹_탭/plan-task.md
+++ b/docs/20260623_메인_콘텐츠_탭_내부_랭킹_탭/plan-task.md
@@ -0,0 +1,634 @@
+# 메인 콘텐츠 탭 내부 랭킹 탭 구현 계획/TASK
+
+> **For agentic workers:** 구현 시 `superpowers:subagent-driven-development` 또는 `superpowers:executing-plans`를 사용해 task 단위로 진행한다. 각 단계는 체크박스(`- [ ]`)로 추적하고, 완료 즉시 `- [x]`로 갱신한다. 구현 범위 변경이 생기면 이 문서를 먼저 수정한 뒤 코드에 반영한다.
+
+**Goal:** `GET /api/v2/audio/rankings?type={AudioRankingType}` 응답을 기반으로 메인 콘텐츠 탭 내부 `랭킹` 탭에 오디오 콘텐츠 랭킹 목록을 표시한다.
+
+**Architecture:** 기존 `ContentMainFragment`와 `fragment_v2_main_content.xml`을 최소 확장해 `추천`, `랭킹`, `전체` Text Tab bar와 랭킹 전용 Capsule Tab bar/RecyclerView를 연결한다. 신규 API/Repository/DTO/UI state/mapper/ViewModel은 `kr.co.vividnext.sodalive.v2.main.content` 하위에 둔다. 기존 `kr.co.vividnext.sodalive.v2.widget.contentranking` 위젯은 `showRankChange=false`일 때 rank-num `GONE` 처리만 필요한 만큼 확장한다.
+
+**Tech Stack:** Kotlin, Android XML Views, ViewBinding, RecyclerView, Retrofit, Gson, RxJava3, Koin, JUnit4/Robolectric local unit test.
+
+---
+
+## 전제와 성공 기준
+- PRD: `docs/20260623_메인_콘텐츠_탭_내부_랭킹_탭/prd.md`
+- Figma 전체 화면: `cont_002` `24:6857`
+- API endpoint는 `GET /api/v2/audio/rankings`이고 선택 타입은 `type` query parameter로 전달한다.
+  - 예: `GET /api/v2/audio/rankings?type=WEEKLY_POPULAR`
+- 내부 Text Tab bar 항목은 `추천`, `랭킹`, `전체` 순서다.
+- Text Tab bar 영역의 `전체` 탭은 항목만 표시하고, 실제 content 화면/API 연동은 이번 범위에서 제외한다.
+- 랭킹 유형 Capsule Tab bar 항목은 `주간 인기`, `지금 뜨는 중`, `매출`, `판매량`, `댓글수`, `좋아요` 순서다.
+- 초기 랭킹 유형은 `WEEKLY_POPULAR`/`주간 인기`다.
+- `rankChange=null` 또는 `0`은 `RankingChangeType.Stay`, amount `0`으로 매핑한다.
+- `rankChange=5`는 `RankingChangeType.Increase`, amount `5`로 매핑한다.
+- `rankChange=-3`은 `RankingChangeType.Decrease`, amount `3`으로 매핑한다.
+- `isNew=true`는 `rankChange`보다 우선해 `RankingChangeType.New`로 매핑한다.
+- `showRankChange=false`이면 모든 rank-num 영역을 `GONE` 처리한다.
+- `rank < 1` item은 표시하지 않고, `contentId <= 0` item은 클릭 이동을 무시한다.
+- API 응답은 서버에서 `rank` 오름차순으로 내려오지만, 클라이언트에서도 한 번 더 `rank` 기준 오름차순 정렬한다.
+- `coverImageUrl=null`은 빈 문자열로 변환하고 기존 이미지 로딩/placeholder 정책을 따른다.
+- 레거시 `AudioContentRankingAllActivity` 또는 기존 오디오 메인 화면 파일은 직접 수정하지 않는다.
+- 구현 완료 후 최소 다음 명령을 실행한다.
+  - `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"`
+  - `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"`
+  - `./gradlew :app:mergeDebugResources`
+  - `./gradlew :app:compileDebugKotlin`
+  - `./gradlew :app:ktlintCheck`
+  - `git diff --check`
+
+---
+
+## Figma 참조 필요 Phase
+- Phase 1: 제한 참조
+  - 기존 콘텐츠 추천 탭, DI, 위젯 구조 확인 중심으로 진행한다.
+- Phase 2: 제한 참조
+  - 기존 콘텐츠 랭킹 위젯 구조와 Figma의 rank-num 숨김 요구를 대조한다.
+- Phase 3: Figma 참조 불필요
+  - API/DTO/mapper/ViewModel은 PRD 서버 계약과 기존 V2 추천 패턴을 따른다.
+- Phase 4: 필수 참조
+  - Text Tab bar, Capsule Tab bar, 랭킹 목록 위치와 visibility 전환은 Figma `24:6857`, `24:6882`를 기준으로 확인한다.
+- Phase 5: 제한 참조
+  - 클릭 routing, loading/error/empty는 기존 `ContentMainFragment` 패턴 중심으로 검증한다.
+- Phase 6: 필수 참조
+  - 최종 수동 화면 검증은 PRD의 모든 포함/제외 항목과 실제 화면을 대조한다.
+
+---
+
+## 파일 구조
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingItem.kt`
+  - `showRankChange` 표시 계약을 기본값 `true`로 추가한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingLargeCardView.kt`
+  - `showRankChange=false`일 때 `ll_content_ranking_delta`를 `GONE` 처리한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingGridCardView.kt`
+  - 2~10위 grid card의 rank-num `GONE` 처리를 추가한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingHorizontalCardView.kt`
+  - 11위 이후 horizontal card의 rank-num `GONE` 처리를 추가한다.
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingCardViewTest.kt`
+  - rank-num visibility와 클릭 가능 상태를 Robolectric으로 검증한다.
+- Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingItemTest.kt`
+  - `showRankChange` 기본값과 false 계약 테스트를 추가한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/data/AudioRankingsApi.kt`
+  - `GET /api/v2/audio/rankings?type=...` Retrofit endpoint를 정의한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/data/AudioRankingsModels.kt`
+  - `AudioRankingResponse`, `AudioRankingType`, `AudioRankingItemResponse` DTO를 정의한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/data/AudioRankingsRepository.kt`
+  - API 호출을 Repository method로 감싼다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/model/AudioRankingsUiState.kt`
+  - `Loading`, `Content`, `Empty`, `Error` 상태와 선택 type 상태를 정의한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/model/AudioRankingsMappers.kt`
+  - DTO를 `ContentRankingItem` 목록으로 변환한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentRankingViewModel.kt`
+  - 랭킹 API 호출, selected type, loading/error/content/toast 상태를 관리한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`
+  - `AudioRankingsApi`, `AudioRankingsRepository`, `ContentRankingViewModel`을 Koin에 등록한다.
+- Modify: `app/src/main/res/layout/fragment_v2_main_content.xml`
+  - Text Tab bar에 `추천`, `랭킹`, `전체`가 표시될 수 있도록 기존 구조를 유지하면서 랭킹 Capsule Tab bar와 RecyclerView를 추가한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragment.kt`
+  - Text Tab 전환, ranking type tab, ranking adapter, ViewModel observe, 오디오 상세 routing을 연결한다.
+- Modify: `app/src/main/res/values/strings.xml`, `app/src/main/res/values-en/strings.xml`, `app/src/main/res/values-ja/strings.xml`
+  - `추천`, `랭킹`, `전체`, 랭킹 유형 라벨 문자열을 추가하거나 기존 문자열을 재사용한다.
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/content/AudioRankingsMapperTest.kt`
+  - DTO -> `ContentRankingItem` 변환 규칙을 검증한다.
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/content/AudioRankingTypeTest.kt`
+  - type별 query value와 UI label 순서를 검증한다.
+- Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragmentSourceTest.kt`
+  - 랭킹 layout id, tab label, adapter/ViewModel observe, routing source를 검증한다.
+
+---
+
+### Phase 1: 기존 구조 확인과 작업 경계 고정
+
+- [x] **Task 1.1: 기존 콘텐츠 추천 탭 구조 확인**
+  - 확인:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragment.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainViewModel.kt`
+    - `app/src/main/res/layout/fragment_v2_main_content.xml`
+    - `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`
+  - 작업:
+    - 추천 탭 `NestedScrollView`와 section visibility 구조를 확인한다.
+    - 랭킹 탭은 기존 추천 section을 리팩터링하지 않고 별도 `RecyclerView` container로 추가하는 경계로 고정한다.
+    - `ContentMainViewModel`은 추천 API 전용으로 유지하고, 랭킹은 신규 `ContentRankingViewModel`로 분리한다.
+  - 검증:
+    - Run: `rg -n "ContentMainViewModel|loadRecommendations|nsv_content_recommendation_content|textTabBarContent|AudioRecommendationsApi" app/src/main/java app/src/main/res`
+    - Expected: 추천 탭 구조와 DI 등록 지점이 확인된다.
+  - 검증 기록:
+    - 2026-06-24: `rg -n "ContentMainViewModel|loadRecommendations|nsv_content_recommendation_content|textTabBarContent|AudioRecommendationsApi" app/src/main/java app/src/main/res` 실행. `ContentMainFragment`, `ContentMainViewModel`, `fragment_v2_main_content.xml`, `AppDI.kt`, `AudioRecommendationsApi`/Repository 참조가 확인되어 추천 탭 구조와 DI 등록 지점을 확인했다.
+
+- [x] **Task 1.2: 콘텐츠 랭킹 위젯 확장 지점 확인**
+  - 확인:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingItem.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingLargeCardView.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingGridCardView.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingHorizontalCardView.kt`
+  - 작업:
+    - `showRankChange` 필드가 없음을 확인한다.
+    - 세 카드 View의 `bindDelta(item)` 시작부가 rank-num visibility 확장 지점임을 확인한다.
+    - `ContentRankingAdapter`의 mixed layout 정책은 그대로 재사용하는 것으로 고정한다.
+  - 검증:
+    - Run: `rg -n "showRankChange|bindDelta|ll_content_ranking_delta|ContentRankingPlacement" app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking`
+    - Expected: `showRankChange`는 없고, `bindDelta`와 `ll_content_ranking_delta` 참조가 확인된다.
+  - 검증 기록:
+    - 2026-06-24: `rg -n "showRankChange|bindDelta|ll_content_ranking_delta|ContentRankingPlacement" app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking` 실행. 기존 `showRankChange`는 없고 `bindDelta`, `ll_content_ranking_delta`, `ContentRankingPlacement` 참조가 확인되어 확장 지점을 고정했다.
+
+- [x] **Task 1.3: 구현 제외 범위 재확인**
+  - 확인:
+    - `docs/20260623_메인_콘텐츠_탭_내부_랭킹_탭/prd.md`
+  - 제외:
+    - Text Tab bar `전체`의 실제 content 화면/API 연동
+    - 레거시 `AudioContentRankingAllActivity` 수정
+    - pagination, pull-to-refresh, skeleton/shimmer
+    - analytics/logging 추가
+    - 추천 탭 section 구조 리팩터링
+  - 검증:
+    - Run: `rg -n "전체|Non-Goals|AudioContentRankingAllActivity|pagination|skeleton" docs/20260623_메인_콘텐츠_탭_내부_랭킹_탭/prd.md`
+    - Expected: 제외 범위가 PRD와 일치한다.
+  - 검증 기록:
+    - 2026-06-24: `rg -n "전체|Non-Goals|AudioContentRankingAllActivity|pagination|skeleton" docs/20260623_메인_콘텐츠_탭_내부_랭킹_탭/prd.md` 실행. `전체` 탭 API/content 제외, legacy `AudioContentRankingAllActivity` 미수정, pagination/skeleton 제외 범위를 재확인했다.
+
+---
+
+### Phase 2: `contentranking` 위젯 rank-num 숨김 계약 확장
+
+- [x] **Task 2.1: `ContentRankingItem` 표시 계약 테스트 추가**
+  - 수정:
+    - `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingItemTest.kt`
+  - 추가 테스트:
+    - `showRankChange` 기본값은 `true`
+    - `showRankChange=false`인 item은 순위 변동 표시 대상이 아님
+    - 기존 `isBlocked`/`isTouchable` 동작은 유지
+  - 구현 예시:
+    ```kotlin
+    @Test
+    fun `showRankChange 기본값은 true다`() {
+        val item = sampleItem()
+
+        assertTrue(item.showRankChange)
+    }
+
+    @Test
+    fun `showRankChange false item은 rank change를 표시하지 않는다`() {
+        val item = sampleItem(showRankChange = false)
+
+        assertFalse(item.showRankChange)
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.ContentRankingItemTest"`
+    - Expected: `showRankChange` 속성 미구현으로 RED 실패.
+  - 검증 기록:
+    - 2026-06-24 RED: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.ContentRankingItemTest"` 실행 시 `Unresolved reference 'showRankChange'`, `No parameter with name 'showRankChange' found`로 실패해 미구현 상태를 확인했다. 같은 실행에서 Phase 3 RED 테스트의 `AudioRankingType` 미구현 실패도 함께 확인되었다.
+
+- [x] **Task 2.2: `ContentRankingItem`에 `showRankChange` 추가**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingItem.kt`
+  - 구현:
+    - 기존 생성자 마지막에 `val showRankChange: Boolean = true`를 추가한다.
+    - 기본값을 둬 기존 호출부 변경을 최소화한다.
+  - 코드 형태:
+    ```kotlin
+    data class ContentRankingItem(
+        val contentId: String,
+        val creatorId: String,
+        val rank: Int,
+        val previousRank: Int?,
+        val rankChangeType: RankingChangeType,
+        val rankChangeAmount: Int?,
+        val contentName: String,
+        val creatorName: String,
+        val imageUrl: String,
+        val isBlocked: Boolean,
+        val showRankChange: Boolean = true
+    )
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.ContentRankingItemTest"`
+    - Expected: PASS.
+  - 검증 기록:
+    - 2026-06-24 GREEN: `ContentRankingItem`에 `showRankChange: Boolean = true`를 추가한 뒤 `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+- [x] **Task 2.3: rank-num `GONE` view 테스트 추가**
+  - 생성:
+    - `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingCardViewTest.kt`
+  - 테스트 케이스:
+    - `ContentRankingLargeCardView`에 `showRankChange=false` item bind 시 `ll_content_ranking_delta`가 `GONE`
+    - `ContentRankingMediumGridCardView`에 `showRankChange=false` item bind 시 `ll_content_ranking_delta`가 `GONE`
+    - `ContentRankingSmallGridCardView`에 `showRankChange=false` item bind 시 `ll_content_ranking_delta`가 `GONE`
+    - `ContentRankingHorizontalCardView`에 `showRankChange=false` item bind 시 `ll_content_ranking_delta`가 `GONE`
+    - `showRankChange=true` item bind 시 `ll_content_ranking_delta`가 `VISIBLE`
+  - 구현 예시:
+    ```kotlin
+    @RunWith(RobolectricTestRunner::class)
+    class ContentRankingCardViewTest {
+        @Test
+        fun `large card는 showRankChange false이면 rank num을 숨긴다`() {
+            val context = ApplicationProvider.getApplicationContext<Context>()
+            val view = LayoutInflater.from(context)
+                .inflate(R.layout.view_content_ranking_large_card, null, false) as ContentRankingLargeCardView
+
+            view.bind(sampleItem(showRankChange = false))
+
+            assertEquals(View.GONE, view.findViewById<View>(R.id.ll_content_ranking_delta).visibility)
+        }
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.ContentRankingCardViewTest"`
+    - Expected: card View rank-num 숨김 미구현으로 RED 실패.
+  - 검증 기록:
+    - 2026-06-24: `ContentRankingCardViewTest`를 추가해 large/medium grid/small grid/horizontal card의 `showRankChange=false` 시 `ll_content_ranking_delta` `GONE`, `true` 시 `VISIBLE` 계약을 검증하도록 했다. 기존 Phase 3 RED 테스트가 전체 unit-test 컴파일을 막아 card 테스트 단독 RED는 별도 분리 실행하지 못했고, 구현 후 widget 패키지 검증에서 함께 GREEN을 확인했다.
+
+- [x] **Task 2.4: rank-num `GONE` 처리 구현**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingLargeCardView.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingGridCardView.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/widget/contentranking/ContentRankingHorizontalCardView.kt`
+  - 구현:
+    - 각 `bindDelta(item)` 시작부에서 `item.showRankChange == false`이면 delta container를 `View.GONE`으로 설정하고 return한다.
+    - `item.showRankChange == true`이면 delta container를 `View.VISIBLE`로 복구한 뒤 기존 presentation 적용을 유지한다.
+  - 코드 형태:
+    ```kotlin
+    private fun bindDelta(item: ContentRankingItem) {
+        val deltaView = requireNotNull(deltaGroup)
+        if (!item.showRankChange) {
+            deltaView.visibility = View.GONE
+            return
+        }
+        deltaView.visibility = View.VISIBLE
+
+        val presentation = ContentRankingDeltaPresentation.from(item.rankChangeType, item.rankChangeAmount)
+        applyDeltaContainer(presentation)
+        ...
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"`
+    - Expected: PASS.
+  - 검증 기록:
+    - 2026-06-24: `ContentRankingLargeCardView`, `ContentRankingGridCardView`, `ContentRankingHorizontalCardView`의 `bindDelta(item)` 시작부에서 `showRankChange=false`이면 delta container를 `View.GONE` 처리하고 return하도록 구현했다. `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"` 실행 결과 `BUILD SUCCESSFUL`.
+
+---
+
+### Phase 3: 랭킹 API/DTO/mapper 작성
+
+- [x] **Task 3.1: `AudioRankingType` 라벨/query 테스트 작성**
+  - 생성:
+    - `app/src/test/java/kr/co/vividnext/sodalive/v2/main/content/AudioRankingTypeTest.kt`
+  - 테스트 케이스:
+    - `AudioRankingType.entries` 순서가 `WEEKLY_POPULAR`, `RISING`, `REVENUE`, `SALES_COUNT`, `COMMENT_COUNT`, `LIKE_COUNT`
+    - query value는 enum name 그대로 사용
+    - label은 `주간 인기`, `지금 뜨는 중`, `매출`, `판매량`, `댓글수`, `좋아요` 순서
+  - 구현 예시:
+    ```kotlin
+    @Test
+    fun `랭킹 타입은 PRD 순서를 유지한다`() {
+        assertEquals(
+            listOf(
+                AudioRankingType.WEEKLY_POPULAR,
+                AudioRankingType.RISING,
+                AudioRankingType.REVENUE,
+                AudioRankingType.SALES_COUNT,
+                AudioRankingType.COMMENT_COUNT,
+                AudioRankingType.LIKE_COUNT
+            ),
+            AudioRankingType.entries
+        )
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.AudioRankingTypeTest"`
+    - Expected: DTO/type 미구현으로 RED 실패.
+  - 검증 기록:
+    - 2026-06-24 RED: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.AudioRankingTypeTest"` 실행 시 `Unresolved reference 'AudioRankingType'`로 실패해 type 미구현 상태를 확인했다.
+
+- [x] **Task 3.2: mapper RED 테스트 작성**
+  - 생성:
+    - `app/src/test/java/kr/co/vividnext/sodalive/v2/main/content/AudioRankingsMapperTest.kt`
+  - 테스트 케이스:
+    - 응답 item을 `rank` 오름차순으로 정렬한다.
+    - `rank < 1` item은 제외한다.
+    - `isNew=true`는 `RankingChangeType.New`, amount `0`으로 매핑한다.
+    - `rankChange=null` 또는 `0`은 `RankingChangeType.Stay`, amount `0`으로 매핑한다.
+    - `rankChange=5`는 `RankingChangeType.Increase`, amount `5`로 매핑한다.
+    - `rankChange=-3`은 `RankingChangeType.Decrease`, amount `3`으로 매핑한다.
+    - `showRankChange=false`이면 모든 `ContentRankingItem.showRankChange=false`로 매핑한다.
+    - `coverImageUrl=null`은 `imageUrl=""`로 매핑한다.
+    - `creatorId`는 API에 없으므로 `ContentRankingItem.creatorId=""`로 매핑한다.
+    - `isBlocked=false`로 매핑한다.
+  - 구현 예시:
+    ```kotlin
+    @Test
+    fun `rankChange 음수는 decrease와 절대값 amount로 매핑된다`() {
+        val item = response(
+            items = listOf(rankingItem(rank = 1, rankChange = -3, isNew = false))
+        ).toContentRankingItems().single()
+
+        assertEquals(RankingChangeType.Decrease, item.rankChangeType)
+        assertEquals(3, item.rankChangeAmount)
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.AudioRankingsMapperTest"`
+    - Expected: DTO/mapper 미구현으로 RED 실패.
+  - 검증 기록:
+    - 2026-06-24: `AudioRankingsMapperTest`를 추가해 rank 정렬/필터, `isNew` 우선, `rankChange` null/0/양수/음수, `showRankChange=false`, `coverImageUrl=null`, `creatorId=""`, `isBlocked=false` 매핑 계약을 검증하도록 했다. 직전 `AudioRankingTypeTest` RED에서 DTO/type 미구현 컴파일 실패를 확인한 뒤 같은 미구현 상태를 전제로 작성했다.
+
+- [x] **Task 3.3: API DTO와 mapper 구현**
+  - 생성:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/data/AudioRankingsModels.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/model/AudioRankingsMappers.kt`
+  - 구현:
+    - `@Keep data class AudioRankingResponse(...)`
+    - `enum class AudioRankingType(...)`
+    - `@Keep data class AudioRankingItemResponse(...)`
+    - PRD 응답 계약에 맞춰 `AudioRankingResponse`에 `type: AudioRankingType`을 포함한다.
+    - Gson `@SerializedName("isNew")`를 사용하고 Jackson `@JsonProperty`는 사용하지 않는다.
+    - `fun AudioRankingResponse.toContentRankingItems(): List<ContentRankingItem>`를 추가한다.
+    - `fun AudioRankingType.labelResId(): Int` 또는 `label(context)` helper는 UI 연결 Phase에서 문자열 리소스와 함께 확정한다.
+  - 코드 형태:
+    ```kotlin
+    @Keep
+    data class AudioRankingItemResponse(
+        @SerializedName("contentId") val contentId: Long,
+        @SerializedName("title") val title: String,
+        @SerializedName("creatorNickname") val creatorNickname: String,
+        @SerializedName("rank") val rank: Int,
+        @SerializedName("rankChange") val rankChange: Int?,
+        @SerializedName("isNew") val isNew: Boolean,
+        @SerializedName("coverImageUrl") val coverImageUrl: String?
+    )
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.AudioRankingTypeTest"`
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.AudioRankingsMapperTest"`
+    - Expected: PASS.
+  - 검증 기록:
+    - 2026-06-24: `AudioRankingsModels.kt`와 `AudioRankingsMappers.kt`를 추가했다. `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"` 실행 결과 `BUILD SUCCESSFUL`.
+    - 2026-06-24 리뷰 보완: 리뷰 게이트에서 PRD 응답 계약의 `type` 누락이 확인되어 `AudioRankingResponse.type: AudioRankingType`을 추가했다.
+
+- [x] **Task 3.4: API/Repository 작성**
+  - 생성:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/data/AudioRankingsApi.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/data/AudioRankingsRepository.kt`
+  - 구현:
+    - `@GET("/api/v2/audio/rankings")`
+    - `@Query("type") type: AudioRankingType`
+    - `@Header("Authorization") authHeader: String`
+    - 반환 타입은 `Single<ApiResponse<AudioRankingResponse>>`
+  - 코드 형태:
+    ```kotlin
+    interface AudioRankingsApi {
+        @GET("/api/v2/audio/rankings")
+        fun getRankings(
+            @Header("Authorization") authHeader: String,
+            @Query("type") type: AudioRankingType
+        ): Single<ApiResponse<AudioRankingResponse>>
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:compileDebugKotlin`
+    - Expected: 신규 API/Repository 컴파일 성공.
+  - 검증 기록:
+    - 2026-06-24: `AudioRankingsApi.kt`, `AudioRankingsRepository.kt`를 추가했다. `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"`에서 신규 API/Repository를 포함한 debug/test 컴파일과 관련 테스트 `BUILD SUCCESSFUL`을 확인했다.
+
+---
+
+### Phase 4: ViewModel과 DI 등록
+
+- [ ] **Task 4.1: UI state와 ViewModel 작성**
+  - 생성:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/model/AudioRankingsUiState.kt`
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentRankingViewModel.kt`
+  - 구현:
+    - `AudioRankingsUiState.Loading`
+    - `AudioRankingsUiState.Content(val type: AudioRankingType, val items: List<ContentRankingItem>)`
+    - `AudioRankingsUiState.Empty(val type: AudioRankingType)`
+    - `AudioRankingsUiState.Error(val type: AudioRankingType, val message: String?)`
+    - `rankingStateLiveData`, `toastLiveData`, `isLoading`, `selectedTypeLiveData`
+    - `loadRankings(type: AudioRankingType, force: Boolean = false)`
+    - 같은 type을 이미 성공 로드했고 `force=false`이면 중복 호출하지 않는다.
+    - 응답 `type`이 현재 선택 type과 다르면 화면 반영을 무시한다.
+    - 기존 `ContentMainViewModel`과 동일하게 `SharedPreferenceManager.token`, RxJava scheduler, unknown error toast 패턴을 사용한다.
+  - 검증:
+    - Run: `./gradlew :app:compileDebugKotlin`
+    - Expected: ViewModel 컴파일 성공.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 4.2: Koin DI 등록**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`
+  - 구현:
+    - import 추가: `AudioRankingsApi`, `AudioRankingsRepository`, `ContentRankingViewModel`
+    - API 등록: `single { ApiBuilder().build(get(), AudioRankingsApi::class.java) }`
+    - Repository 등록: `factory { AudioRankingsRepository(get()) }`
+    - ViewModel 등록: `viewModel { ContentRankingViewModel(get()) }`
+  - 검증:
+    - Run: `./gradlew :app:compileDebugKotlin`
+    - Expected: Koin 등록과 import 컴파일 성공.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+---
+
+### Phase 5: 레이아웃과 탭 전환 UI 연결
+
+- [ ] **Task 5.1: 랭킹 layout/source RED 테스트 추가**
+  - 수정:
+    - `app/src/test/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragmentSourceTest.kt`
+  - 추가 테스트:
+    - `fragment_v2_main_content.xml`에 `view_content_ranking_type_tabs`가 존재한다.
+    - `fragment_v2_main_content.xml`에 `rv_content_rankings`가 존재한다.
+    - `ContentMainFragment` source에 `ContentRankingViewModel by viewModel()`이 존재한다.
+    - `ContentMainFragment` source에 `ContentRankingAdapter.createGridLayoutManager(requireContext())`가 존재한다.
+    - `ContentMainFragment` source에 `AudioRankingType.WEEKLY_POPULAR` 초기 로드가 존재한다.
+    - `ContentMainFragment` source에 Text Tab 메뉴 `추천`, `랭킹`, `전체` 설정이 존재한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.ContentMainFragmentSourceTest"`
+    - Expected: layout id/ViewModel/adapter 연결 미구현으로 RED 실패.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 5.2: strings 추가**
+  - 수정:
+    - `app/src/main/res/values/strings.xml`
+    - `app/src/main/res/values-en/strings.xml`
+    - `app/src/main/res/values-ja/strings.xml`
+  - 구현:
+    - `screen_content_tab_recommendation`
+    - `screen_content_tab_ranking`
+    - `screen_content_tab_all`
+    - `screen_content_ranking_type_weekly_popular`
+    - `screen_content_ranking_type_rising`
+    - `screen_content_ranking_type_revenue`
+    - `screen_content_ranking_type_sales_count`
+    - `screen_content_ranking_type_comment_count`
+    - `screen_content_ranking_type_like_count`
+  - 검증:
+    - Run: `./gradlew :app:mergeDebugResources`
+    - Expected: 문자열 리소스 merge 성공.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 5.3: `fragment_v2_main_content.xml`에 랭킹 container 추가**
+  - 수정:
+    - `app/src/main/res/layout/fragment_v2_main_content.xml`
+  - 구현:
+    - 기존 `text_tab_bar_content` 아래에 랭킹 type tab include를 추가한다.
+    - `@+id/view_content_ranking_type_tabs`, `layout="@layout/view_capsule_tab_bar"`, 초기 `android:visibility="gone"`로 둔다.
+    - 랭킹 RecyclerView `@+id/rv_content_rankings`를 추가한다.
+    - `rv_content_rankings`는 `view_content_ranking_type_tabs` 아래부터 parent bottom까지 constraint하고 초기 `gone`으로 둔다.
+    - 기존 `nsv_content_recommendation_content`는 추천 탭 선택 시만 visible로 유지한다.
+  - XML 형태:
+    ```xml
+    <include
+        android:id="@+id/view_content_ranking_type_tabs"
+        layout="@layout/view_capsule_tab_bar"
+        android:layout_width="0dp"
+        android:layout_height="52dp"
+        android:visibility="gone"
+        app:layout_constraintEnd_toEndOf="parent"
+        app:layout_constraintStart_toStartOf="parent"
+        app:layout_constraintTop_toBottomOf="@id/text_tab_bar_content" />
+
+    <androidx.recyclerview.widget.RecyclerView
+        android:id="@+id/rv_content_rankings"
+        android:layout_width="0dp"
+        android:layout_height="0dp"
+        android:clipToPadding="false"
+        android:paddingHorizontal="@dimen/spacing_14"
+        android:paddingTop="@dimen/spacing_14"
+        android:paddingBottom="@dimen/spacing_28"
+        android:visibility="gone"
+        app:layout_constraintBottom_toBottomOf="parent"
+        app:layout_constraintEnd_toEndOf="parent"
+        app:layout_constraintStart_toStartOf="parent"
+        app:layout_constraintTop_toBottomOf="@id/view_content_ranking_type_tabs" />
+    ```
+  - 검증:
+    - Run: `./gradlew :app:mergeDebugResources`
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.ContentMainFragmentSourceTest"`
+    - Expected: resource merge 성공, source test는 Fragment 연결 전 일부 RED 유지 가능.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 5.4: `ContentMainFragment`에 Text Tab 전환과 랭킹 탭 UI 연결**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragment.kt`
+  - 구현:
+    - `private val contentRankingViewModel: ContentRankingViewModel by viewModel()` 추가
+    - `ContentRankingAdapter { openAudioContentDetail(it.contentId.toLongOrNull() ?: 0L) }` 추가
+    - `binding.textTabBarContent.root.setMenus(listOf(...추천, ...랭킹, ...전체), selectedIndex = 0)`로 변경
+    - Text Tab index 상수 추가:
+      - `CONTENT_TAB_RECOMMENDATION = 0`
+      - `CONTENT_TAB_RANKING = 1`
+      - `CONTENT_TAB_ALL = 2`
+    - `랭킹` 선택 시 추천 scroll을 `GONE`, ranking type tab과 ranking RecyclerView를 `VISIBLE`로 전환한다.
+    - `전체` 선택 시 항목만 선택되지만 실제 content 구현은 제외하므로 추천/랭킹 content를 모두 숨기거나 기존 화면 정책에 맞춰 빈 화면을 유지한다. 이 동작은 계획 실행 중 사용자 확인 없이 추가 API 연동으로 확장하지 않는다.
+    - `랭킹` 최초 선택 시 `AudioRankingType.WEEKLY_POPULAR`를 로드한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.ContentMainFragmentSourceTest"`
+    - Expected: Fragment source 연결 관련 assertion PASS.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 5.5: 랭킹 유형 Capsule Tab 연결**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragment.kt`
+  - 구현:
+    - `view_content_ranking_type_tabs.root.setMenus(...)`로 6개 라벨을 설정한다.
+    - `setOnTabSelectedListener`에서 index를 `AudioRankingType.entries[index]`로 변환한다.
+    - 같은 type 재선택은 `CapsuleTabBarView.selectTab()` 내부에서 무시되므로 별도 API 호출을 만들지 않는다.
+    - 탭 전환 시 `contentRankingViewModel.loadRankings(type)`를 호출한다.
+  - 검증:
+    - Run: `./gradlew :app:compileDebugKotlin`
+    - Expected: Capsule Tab 연결 컴파일 성공.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 5.6: ranking observer와 adapter submit 연결**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragment.kt`
+  - 구현:
+    - `rv_content_rankings.layoutManager = ContentRankingAdapter.createGridLayoutManager(requireContext())`
+    - `rv_content_rankings.adapter = contentRankingAdapter`
+    - `rankingStateLiveData.observe(viewLifecycleOwner)`에서 `Content`이면 `submitItems(state.items)`, `Empty`/`Error`이면 `submitItems(emptyList())`
+    - `isLoading`은 기존 `LoadingDialog`와 충돌하지 않도록 추천/랭킹 ViewModel의 loading 상태를 모두 관찰하거나, 랭킹 loading만 별도 observer에서 같은 dialog를 show/dismiss한다.
+    - `toastLiveData`는 기존 `showToast` helper를 재사용한다.
+  - 검증:
+    - Run: `./gradlew :app:compileDebugKotlin`
+    - Expected: Fragment/adapter/ViewModel 연결 컴파일 성공.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+---
+
+### Phase 6: routing, 통합 검증, 문서 검증 기록
+
+- [ ] **Task 6.1: 랭킹 item 클릭 routing guard 연결**
+  - 수정:
+    - `app/src/main/java/kr/co/vividnext/sodalive/v2/main/content/ContentMainFragment.kt`
+  - 구현:
+    - `ContentRankingItem.contentId`를 `Long`으로 변환한다.
+    - `contentId > 0`이면 기존 `openAudioContentDetail(audioContentId)`를 호출한다.
+    - 변환 실패 또는 `contentId <= 0`이면 아무 동작하지 않는다.
+  - 코드 형태:
+    ```kotlin
+    private fun openRankingAudioContentDetail(item: ContentRankingItem) {
+        val audioContentId = item.contentId.toLongOrNull() ?: return
+        openAudioContentDetail(audioContentId)
+    }
+    ```
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.ContentMainFragmentSourceTest"`
+    - Expected: routing source assertion PASS.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 6.2: mapper/widget/content package 단위 테스트 실행**
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"`
+    - Expected: PASS.
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"`
+    - Expected: PASS.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 6.3: 리소스/컴파일/스타일 검증**
+  - 검증:
+    - Run: `./gradlew :app:mergeDebugResources`
+    - Expected: `BUILD SUCCESSFUL`
+    - Run: `./gradlew :app:compileDebugKotlin`
+    - Expected: `BUILD SUCCESSFUL`
+    - Run: `./gradlew :app:ktlintCheck`
+    - Expected: `BUILD SUCCESSFUL`
+    - Run: `git diff --check`
+    - Expected: trailing whitespace 또는 conflict marker 없음
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+- [ ] **Task 6.4: 수동 화면 검증**
+  - 확인:
+    - 메인 콘텐츠 탭 진입 시 기본 `추천` 탭 화면이 기존처럼 표시된다.
+    - Text Tab bar에 `추천`, `랭킹`, `전체`이 보인다.
+    - `랭킹` 선택 시 Capsule Tab bar 6개 항목이 Figma 순서로 보인다.
+    - 초기 선택은 `주간 인기`이고 API는 `type=WEEKLY_POPULAR`로 호출된다.
+    - 랭킹 목록은 1위 대형, 2~7위 2열, 8~10위 3열, 11위 이후 가로형으로 표시된다.
+    - `showRankChange=false` 응답에서 rank-num 영역이 보이지 않는다.
+    - `contentId > 0` item 터치 시 오디오 상세로 이동한다.
+    - `전체` 탭은 항목만 표시하고 별도 API/content 구현이 없다.
+  - 검증 기록:
+    - 구현 시 실행 결과를 이 아래에 누적한다.
+
+---
+
+## Verification Log
+- 구현 중 여러 Phase에 걸친 통합 검증, 회귀 검증, 최종 수동 확인 기록을 이 아래에 누적한다.
+- 2026-06-24: Phase 1~3 구현 후 `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"` 실행 결과 `BUILD SUCCESSFUL`.
+- 2026-06-24: Phase 1~3 구현 후 `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"` 실행 결과 `BUILD SUCCESSFUL`.
+- 2026-06-24: `./gradlew :app:mergeDebugResources` 실행 결과 `BUILD SUCCESSFUL`.
+- 2026-06-24: `./gradlew :app:compileDebugKotlin` 실행 결과 `BUILD SUCCESSFUL`.
+- 2026-06-24: `./gradlew :app:ktlintCheck` 1차 실행에서 변경 파일의 기존 긴 `LayoutParams` 라인이 ktlint max line length를 위반해 실패했고, 기능 변경 없이 줄바꿈만 정리한 뒤 재실행 결과 `BUILD SUCCESSFUL`. `.editorconfig`의 `disabled_rules` deprecation 경고는 기존 설정 경고로 남아 있다.
+- 2026-06-24: `git diff --check` 실행 결과 출력 없음. trailing whitespace 또는 conflict marker 없음.
+- 2026-06-24: Kotlin LSP 진단은 환경에 `kotlin-lsp`가 설치되어 있지 않아 실행 불가(`Command not found: kotlin-lsp`). Gradle compile/test/ktlint로 대체 검증했다.
+- 2026-06-24: 리뷰 게이트 보완 후 `AudioRankingResponse.type` 추가. `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"`, `./gradlew :app:compileDebugKotlin`, `./gradlew :app:ktlintCheck`, `git diff --check` 재실행 결과 모두 통과했다.
+- 2026-06-24: Phase 1~3 코드 리뷰 및 현재 워크트리 기준 재검증을 수행했다. Phase 1 구조 확인용 `rg` 3개 명령에서 기대 참조를 확인했고, `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.widget.contentranking.*"`, `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.content.*"`, `./gradlew :app:compileDebugKotlin`, `./gradlew :app:ktlintCheck`, `git diff --check` 실행 결과 모두 통과했다. `./gradlew :app:mergeDebugResources`는 샌드박스 내 Gradle wrapper lock 접근 제한으로 1차 실패 후 권한 상승 실행에서 `BUILD SUCCESSFUL`을 확인했다.