docs(content-ranking): 랭킹 탭 API 요구사항과 계획을 기록한다

2026-06-24 00:10:25 +09:00
parent 2a7d74b018
commit d44f890391
2 changed files with 836 additions and 0 deletions
--- a/docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md
+++ b/docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md
@@ -0,0 +1,481 @@
+# 메인 콘텐츠 랭킹 탭 API Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` 또는 `superpowers:executing-plans`로 task 단위 구현을 진행한다. 각 단계는 체크박스(`- [ ]`)로 진행 상태를 갱신한다.
+
+**Goal:** `GET /api/v2/audio/rankings`로 메인 콘텐츠 랭킹 탭의 6개 랭킹 타입을 스냅샷 기반으로 조회하고, 순위/순위 변화/신규 진입 여부를 안정적으로 제공한다.
+
+**Architecture:** 공개 API controller/facade/response DTO는 `kr.co.vividnext.sodalive.v2.api.content.ranking` 조립 계층에 둔다. 콘텐츠 랭킹 계산, 스냅샷 조회/생성, fallback, scheduler, legacy adapter는 `kr.co.vividnext.sodalive.v2.content.ranking` 하위에 두고 `v2.api.*`에 의존하지 않는다. 스냅샷은 `rankingType + aggregation period + visibleFromAt`을 기준으로 저장하고, 조회 API는 `visibleFromAt <= now`인 생성 완료 스냅샷만 공개 응답에 사용한다.
+
+**Tech Stack:** Kotlin, Spring Boot 2.7.14, Java 17, Spring MVC, Spring Data JPA, QueryDSL/native SQL, Redisson, JUnit 5, MockMvc, Gradle Wrapper
+
+---
+
+## 0. 구현 전 확정 사항
+
+- API endpoint: `GET /api/v2/audio/rankings`
+- 요청 query parameter: `type`, 기본값 `WEEKLY_POPULAR`
+- 랭킹 타입:
+  - `WEEKLY_POPULAR`: 주간 인기
+  - `RISING`: 지금 뜨는 중
+  - `REVENUE`: 매출
+  - `SALES_COUNT`: 판매량
+  - `COMMENT_COUNT`: 댓글 수
+  - `LIKE_COUNT`: 좋아요
+- 모든 랭킹 타입은 완료된 지난 주 데이터를 기준으로 한다.
+- 집계 기준 시각: 매주 월요일 `00:00:00 KST`
+- 스냅샷 생성 시간대: 매주 월요일 `01:00:00 ~ 07:30:00 KST` 사이 랭킹 타입별 분산 실행
+- 새 스냅샷 노출 전환 시각: 매주 월요일 `09:00:00 KST`
+- 조회 API는 `visibleFromAt <= now`인 최신 완료 스냅샷만 응답한다.
+- 09:00 전에는 새 스냅샷이 생성되어도 직전 공개 스냅샷을 응답한다.
+- 특정 랭킹 타입의 새 스냅샷 생성이 실패하면 해당 타입은 직전 공개 스냅샷을 유지한다.
+- fallback은 요청한 랭킹 타입과 동일 집계 기간 기준 최대 3회까지만 실행한다.
+- 이번 범위는 콘텐츠 랭킹만 수정한다.
+- 크리에이터 랭킹의 생성 시간/표시 시간 분리와 다중 랭킹 타입 대응은 다음 범위에서 별도 PRD 문서 수정부터 시작한다.
+
+---
+
+## 1. 파일 구조 계획
+
+### 신규 API 조립 계층
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/adapter/in/web/AudioRankingController.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/application/AudioRankingFacade.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/dto/AudioRankingResponse.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/adapter/in/web/AudioRankingControllerTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/application/AudioRankingFacadeTest.kt`
+
+### 신규 콘텐츠 랭킹 도메인 계층
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingType.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRanking.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingPeriodPolicy.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingScorePolicy.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingSchedulePolicy.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingPeriodPolicyTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingScorePolicyTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingSchedulePolicyTest.kt`
+
+### 신규 콘텐츠 랭킹 application/port
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryService.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotRefreshService.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotJobService.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingSnapshotPort.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingSnapshotJobPort.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingAggregationPort.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingBlockPort.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryServiceTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotRefreshServiceTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotJobServiceTest.kt`
+
+### 신규 persistence/scheduler/legacy adapter
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshot.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshotJob.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshotRepository.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshotJobRepository.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapter.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingAggregationRepository.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingBlockRepository.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/legacy/LegacyAudioRankingAdapter.kt`
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/scheduler/AudioRankingSnapshotScheduler.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapterTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingAggregationRepositoryTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/legacy/LegacyAudioRankingAdapterTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/scheduler/AudioRankingSnapshotSchedulerTest.kt`
+
+### 문서/DDL
+- Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/create-content-ranking-tables.sql`
+- Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/prd.md`
+- Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md`
+- Verify: `docs/20260608_크리에이터_랭킹/prd.md`
+- Verify: `docs/20260608_크리에이터_랭킹/plan-task.md`
+- Verify: `docs/20260608_크리에이터_랭킹/create-ranking-tables.sql`
+
+---
+
+## 2. Response data class 초안
+
+구현 시 `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/dto/AudioRankingResponse.kt`에 아래 DTO를 기준으로 추가한다. 필드명은 공개 API 계약이므로 변경이 필요하면 먼저 PRD와 이 문서를 갱신한다.
+
+```kotlin
+package kr.co.vividnext.sodalive.v2.api.content.ranking.dto
+
+import com.fasterxml.jackson.annotation.JsonProperty
+import kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRanking
+import kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRankingItem
+import kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRankingType
+
+data class AudioRankingResponse(
+    val showRankChange: Boolean,
+    val type: AudioRankingType,
+    val items: List<AudioRankingItemResponse>
+) {
+    companion object {
+        fun from(ranking: AudioRanking): AudioRankingResponse {
+            return AudioRankingResponse(
+                showRankChange = ranking.showRankChange,
+                type = ranking.type,
+                items = ranking.items.map(AudioRankingItemResponse::from)
+            )
+        }
+    }
+}
+
+data class AudioRankingItemResponse(
+    val contentId: Long,
+    val title: String,
+    val creatorNickname: String,
+    val rank: Int,
+    val rankChange: Int?,
+    @JsonProperty("isNew")
+    val isNew: Boolean,
+    val coverImageUrl: String?
+) {
+    companion object {
+        fun from(item: AudioRankingItem): AudioRankingItemResponse {
+            return AudioRankingItemResponse(
+                contentId = item.contentId,
+                title = item.title,
+                creatorNickname = item.creatorNickname,
+                rank = item.rank,
+                rankChange = item.rankChange,
+                isNew = item.isNew,
+                coverImageUrl = item.coverImageUrl
+            )
+        }
+    }
+}
+```
+
+---
+
+## 3. Domain / Port 초안
+
+```kotlin
+package kr.co.vividnext.sodalive.v2.content.ranking.domain
+
+enum class AudioRankingType {
+    WEEKLY_POPULAR,
+    RISING,
+    REVENUE,
+    SALES_COUNT,
+    COMMENT_COUNT,
+    LIKE_COUNT
+}
+
+data class AudioRanking(
+    val showRankChange: Boolean,
+    val type: AudioRankingType,
+    val items: List<AudioRankingItem>
+)
+
+data class AudioRankingItem(
+    val contentId: Long,
+    val title: String,
+    val creatorNickname: String,
+    val rank: Int,
+    val rankChange: Int?,
+    val isNew: Boolean,
+    val coverImageUrl: String?
+)
+```
+
+```kotlin
+package kr.co.vividnext.sodalive.v2.content.ranking.port.out
+
+import kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRankingType
+import java.time.LocalDateTime
+
+interface AudioRankingSnapshotPort {
+    fun findLatestVisibleSnapshots(
+        rankingType: AudioRankingType,
+        nowUtc: LocalDateTime
+    ): List<AudioRankingSnapshotRecord>
+
+    fun findPreviousVisibleSnapshots(
+        rankingType: AudioRankingType,
+        currentAggregationStartAtUtc: LocalDateTime,
+        nowUtc: LocalDateTime
+    ): List<AudioRankingSnapshotRecord>
+
+    fun replaceSnapshots(
+        rankingType: AudioRankingType,
+        aggregationStartAtUtc: LocalDateTime,
+        aggregationEndAtUtc: LocalDateTime,
+        visibleFromAtUtc: LocalDateTime,
+        newSnapshots: List<AudioRankingSnapshotRecord>
+    )
+}
+
+data class AudioRankingSnapshotRecord(
+    val rankingType: AudioRankingType,
+    val aggregationStartAtUtc: LocalDateTime,
+    val aggregationEndAtUtc: LocalDateTime,
+    val visibleFromAtUtc: LocalDateTime,
+    val contentId: Long,
+    val title: String,
+    val creatorMemberId: Long,
+    val creatorNickname: String,
+    val coverImageUrl: String?,
+    val releaseDate: LocalDateTime,
+    val rank: Int,
+    val finalScore: Double
+)
+```
+
+---
+
+### Phase 1: API 계약과 DTO
+
+- [ ] **Task 1.1: `AudioRankingType`과 응답 DTO 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingType.kt`
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRanking.kt`
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/dto/AudioRankingResponse.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/dto/AudioRankingResponseTest.kt`
+  - RED: `AudioRankingResponse.from(...)`이 `showRankChange`, `type`, `contentId`, `title`, `creatorNickname`, `rank`, `rankChange`, `isNew`, `coverImageUrl`을 변환하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.content.ranking.dto.AudioRankingResponseTest`
+  - GREEN: DTO와 domain model을 최소 구현한다.
+  - REFACTOR: 공개 DTO가 persistence/entity를 import하지 않도록 확인한다.
+  - 기대 결과: PRD의 Response data class 계약이 테스트로 고정된다.
+
+- [ ] **Task 1.2: facade 변환 계층 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/application/AudioRankingFacade.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/application/AudioRankingFacadeTest.kt`
+  - RED: facade가 `AudioRankingQueryService.getRankings(type, member)` 결과를 `AudioRankingResponse`로 변환하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.content.ranking.application.AudioRankingFacadeTest`
+  - GREEN: facade는 query service 호출과 DTO 변환만 담당한다.
+  - REFACTOR: facade에 점수 계산, 스냅샷 조회, fallback 로직을 두지 않는다.
+  - 기대 결과: API 조립 계층과 도메인 조회 계층 의존 방향이 고정된다.
+
+- [ ] **Task 1.3: 비회원 허용 controller 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/adapter/in/web/AudioRankingController.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/adapter/in/web/AudioRankingControllerTest.kt`
+  - RED: `GET /api/v2/audio/rankings`가 비회원과 인증 회원 모두 `200 OK`를 반환하고, `type` 미지정 시 `WEEKLY_POPULAR`로 facade를 호출하는 MockMvc 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.content.ranking.adapter.in.web.AudioRankingControllerTest`
+  - GREEN: `@AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?` 패턴과 `@RequestParam` 기본값을 적용한다.
+  - REFACTOR: controller에는 인증/요청/응답 경계만 남긴다.
+  - 기대 결과: endpoint 경로, 기본 type, wrapper 응답 계약이 controller 테스트로 고정된다.
+
+### Phase 2: 기간/노출/점수 정책
+
+- [ ] **Task 2.1: KST 주간 집계 기간과 UTC 변환 정책 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingPeriodPolicy.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingPeriodPolicyTest.kt`
+  - RED: 임의의 KST 수요일 기준으로 지난 주 월요일 00:00 KST 이상, 이번 주 월요일 00:00 KST 미만 기간을 산출하고 UTC `LocalDateTime`으로 변환하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRankingPeriodPolicyTest`
+  - GREEN: `resolveLastCompletedWeek(now)`와 `toUtcRange(period)`를 구현한다.
+  - REFACTOR: 서버 기본 timezone에 의존하지 않고 `ZoneId.of("Asia/Seoul")`을 명시한다.
+  - 기대 결과: 모든 랭킹 타입의 집계 기준 기간이 동일하게 계산된다.
+
+- [ ] **Task 2.2: 09:00 노출 전환 정책 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingSchedulePolicy.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingSchedulePolicyTest.kt`
+  - RED: 집계 종료일 월요일 기준 `visibleFromAt`이 같은 날 09:00 KST의 UTC 시각으로 계산되고, 09:00 전에는 새 스냅샷이 공개되지 않는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRankingSchedulePolicyTest`
+  - GREEN: `resolveVisibleFromAt(aggregationEndAtKst)`와 `isVisible(visibleFromAtUtc, nowUtc)`를 구현한다.
+  - REFACTOR: scheduler 실행 시각과 공개 노출 시각을 별도 함수로 분리한다.
+  - 기대 결과: 계산 완료와 공개 노출 전환이 분리된다.
+
+- [ ] **Task 2.3: 주간 인기/지금 뜨는 중 점수 정책 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingScorePolicy.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/domain/AudioRankingScorePolicyTest.kt`
+  - RED: 유료/무료 주간 인기 원점수, 0~100 정규화, 지금 뜨는 중 증가율, 최소 반영 기준, 신규 콘텐츠 부스트를 검증하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.domain.AudioRankingScorePolicyTest`
+  - GREEN: `calculateWeeklyPopularScore`, `normalizeScore`, `calculateRisingScore`, `applyMinimumThreshold`, `releaseBoost`를 구현한다.
+  - REFACTOR: 가중치와 최소 기준은 `companion object` 상수로 모은다.
+  - 기대 결과: PRD 산식과 “기준 미달 지표만 0점 처리” 정책이 순수 단위 테스트로 고정된다.
+
+### Phase 3: 스냅샷 Entity/Port/DDL
+
+- [ ] **Task 3.1: 스냅샷 Entity와 port 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshot.kt`
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingSnapshotPort.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingSnapshotPersistenceAdapterTest.kt`
+  - RED: `visibleFromAtUtc <= nowUtc`인 최신 스냅샷만 조회하고, 09:00 전에는 이전 visible 스냅샷을 반환하는 persistence adapter 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.adapter.out.persistence.DefaultAudioRankingSnapshotPersistenceAdapterTest`
+  - GREEN: `AudioRankingSnapshot`, `AudioRankingSnapshotRepository`, `DefaultAudioRankingSnapshotPersistenceAdapter`를 구현한다.
+  - REFACTOR: `rankingType`, `aggregationStartAtUtc`, `aggregationEndAtUtc`, `visibleFromAtUtc` 필드명을 DDL과 맞춘다.
+  - 기대 결과: 공개 조회 기준이 `latest generated`가 아니라 `latest visible`로 고정된다.
+
+- [ ] **Task 3.2: 스냅샷 job Entity와 port 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshotJob.kt`
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingSnapshotJobPort.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotJobServiceTest.kt`
+  - RED: `SCHEDULED`, `MANUAL`, `FALLBACK` trigger와 `PENDING`, `PROCESSING`, `DONE`, `FAILED` 상태를 저장/변경할 수 있는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingSnapshotJobServiceTest`
+  - GREEN: job entity, repository, port adapter를 구현한다.
+  - REFACTOR: fallback 3회 제한 조회에 필요한 `rankingType + aggregation period + triggerType` 조건을 port에 둔다.
+  - 기대 결과: 스케줄 실행과 fallback 실행이 모두 job 이력으로 추적된다.
+
+- [ ] **Task 3.3: DDL 문서와 Entity 필드 정합성 확인**
+  - Files:
+    - Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/create-content-ranking-tables.sql`
+    - Verify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshot.kt`
+    - Verify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/AudioRankingSnapshotJob.kt`
+  - TDD 예외 사유: DDL 문서와 JPA Entity 필드 정합성 확인 task이므로 신규 실패 테스트 작성 대상이 아니다.
+  - 대체 검증 방법:
+    - Run: `rg -n "visible_from_at|content_ranking_snapshot|content_ranking_snapshot_job" docs/20260623_메인_콘텐츠_랭킹_탭_API src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking`
+    - Run: `./gradlew tasks --all`
+  - 기대 결과: 신규 Entity에 대응하는 운영 DB DDL이 같은 작업 디렉터리에 기록되어 있다.
+
+### Phase 4: 랭킹 후보 집계와 legacy 재사용
+
+- [ ] **Task 4.1: legacy 정렬 랭킹 adapter 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/legacy/LegacyAudioRankingAdapter.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/legacy/LegacyAudioRankingAdapterTest.kt`
+  - RED: `REVENUE`, `SALES_COUNT`, `COMMENT_COUNT`, `LIKE_COUNT`가 각각 `ContentRankingSortType.REVENUE`, `SALES_COUNT`, `COMMENT_COUNT`, `LIKE_COUNT`로 매핑되는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.adapter.out.legacy.LegacyAudioRankingAdapterTest`
+  - GREEN: 기존 `RankingService.getContentRanking(...)`을 port 경계 뒤에서 호출한다.
+  - REFACTOR: v2 application service가 legacy service를 직접 import하지 않도록 한다.
+  - 기대 결과: 기존 산식 4종을 재정의하지 않고 재사용한다.
+
+- [ ] **Task 4.2: 주간 인기/지금 뜨는 중 후보 집계 repository 작성**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingAggregationPort.kt`
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingAggregationRepository.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingAggregationRepositoryTest.kt`
+  - RED: 상세 조회수, 매출, 판매량, 좋아요, 댓글 수를 집계하고 비활성/공개 전/비활성 크리에이터 콘텐츠를 제외하는 repository 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.adapter.out.persistence.DefaultAudioRankingAggregationRepositoryTest`
+  - GREEN: QueryDSL 또는 native SQL로 주간 인기와 지금 뜨는 중 후보 원천 지표를 조회한다.
+  - REFACTOR: 공개 오디오 조건, 성인 콘텐츠 조건, 차단 관계 조건을 private 조건 함수로 분리한다.
+  - 기대 결과: 신규 산식 2종의 원천 지표가 application service에 전달된다.
+
+- [ ] **Task 4.3: 동점 정렬과 Top 20 스냅샷 후보 생성**
+  - Files:
+    - Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotRefreshService.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotRefreshServiceTest.kt`
+  - RED: 최종 점수 동점이면 `releaseDate desc`, `contentId desc` 순으로 최대 20개를 저장하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingSnapshotRefreshServiceTest`
+  - GREEN: 후보별 점수 계산, 정규화, 정렬, rank 부여, snapshot record 변환을 구현한다.
+  - REFACTOR: 점수 계산은 `AudioRankingScorePolicy`, 기간/노출 시각 계산은 policy에 위임한다.
+  - 기대 결과: 스냅샷 생성 결과가 조회 시 재정렬되지 않아도 안정적인 순위를 가진다.
+
+### Phase 5: 스냅샷 생성 job과 분산 scheduler
+
+- [ ] **Task 5.1: 랭킹 타입별 refresh service 구현**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotRefreshService.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotRefreshServiceTest.kt`
+  - RED: 각 `AudioRankingType`에 대해 집계 기간, `visibleFromAt`, 후보 목록을 계산해 기존 스냅샷을 replace하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingSnapshotRefreshServiceTest`
+  - GREEN: `refreshLastCompletedWeek(type, now)`를 구현하고 `AudioRankingSnapshotPort.replaceSnapshots(...)`를 호출한다.
+  - REFACTOR: 특정 타입 실패가 다른 타입 refresh를 막지 않도록 job service에서 타입 단위 실행을 분리한다.
+  - 기대 결과: 랭킹 타입별 독립 스냅샷 생성이 가능하다.
+
+- [ ] **Task 5.2: job service와 fallback 3회 제한 구현**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotJobService.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingSnapshotJobServiceTest.kt`
+  - RED: scheduled job이 `PENDING -> PROCESSING -> DONE/FAILED`로 상태 변경되고, 같은 타입/기간 fallback이 3회 이상이면 refresh를 호출하지 않는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingSnapshotJobServiceTest`
+  - GREEN: job 생성, 상태 변경, fallback 제한, 기간 기반 Redisson lock 경계를 구현한다.
+  - REFACTOR: job 이력 저장은 `REQUIRES_NEW` 트랜잭션 패턴을 검토해 크리에이터 랭킹 job service와 맞춘다.
+  - 기대 결과: fallback과 scheduled refresh가 같은 job 이력 구조를 사용한다.
+
+- [ ] **Task 5.3: 01:00~07:30 분산 scheduler 구현**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/scheduler/AudioRankingSnapshotScheduler.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/scheduler/AudioRankingSnapshotSchedulerTest.kt`
+  - RED: 랭킹 타입별 scheduler method가 `Asia/Seoul` zone과 서로 다른 cron을 가지고, lock 획득 성공 시에만 job service를 호출하는 reflection/Mockito 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.adapter.out.scheduler.AudioRankingSnapshotSchedulerTest`
+  - GREEN: 예시 배치로 `WEEKLY_POPULAR 02:00`, `RISING 03:00`, `REVENUE 04:00`, `SALES_COUNT 05:00`, `COMMENT_COUNT 06:00`, `LIKE_COUNT 07:00` KST scheduler를 구현한다.
+  - REFACTOR: lock key는 `lock:content-ranking-snapshot-refresh:{rankingType}` 형태로 목적과 타입이 드러나게 한다.
+  - 기대 결과: 콘텐츠 랭킹 스냅샷 생성이 01:00~07:30 범위 안에서 타입별로 분산된다.
+
+### Phase 6: 조회 서비스와 순위 변화 계산
+
+- [ ] **Task 6.1: 최신/직전 visible 스냅샷 조회와 rankChange 계산**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryService.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryServiceTest.kt`
+  - RED: 직전 공개 스냅샷이 있으면 `rankChange = previousRank - currentRank`, 신규 진입은 `isNew=true`, 직전 스냅샷이 없으면 `showRankChange=false`가 되는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingQueryServiceTest`
+  - GREEN: `getRankings(type, member)`에서 최신 visible 스냅샷과 직전 visible 스냅샷을 조회해 `AudioRanking`을 조립한다.
+  - REFACTOR: 순위 변화 계산은 별도 private 함수로 분리한다.
+  - 기대 결과: 크리에이터 랭킹과 같은 의미의 `rank`, `rankChange`, `isNew`가 콘텐츠 랭킹에도 적용된다.
+
+- [ ] **Task 6.2: 차단/성인 콘텐츠 정책 반영**
+  - Files:
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/port/out/AudioRankingBlockPort.kt`
+    - Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/adapter/out/persistence/DefaultAudioRankingBlockRepository.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryServiceTest.kt`
+  - RED: 비회원은 성인 콘텐츠를 제외하고, 회원 차단 관계가 있는 콘텐츠는 기존 콘텐츠 랭킹/추천 정책에 맞게 제외 또는 마스킹되는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingQueryServiceTest`
+  - GREEN: 조회 조건 또는 응답 조립 단계에서 성인 콘텐츠/차단 관계 정책을 적용한다.
+  - REFACTOR: 기존 콘텐츠 추천 탭의 성인 콘텐츠 조회 가능 여부 계산 경로를 재사용한다.
+  - 기대 결과: 공개 조회 정책이 기존 v2 콘텐츠 추천/랭킹 정책과 어긋나지 않는다.
+
+- [ ] **Task 6.3: 스냅샷 없음 fallback 조회 보강**
+  - Files:
+    - Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryService.kt`
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/ranking/application/AudioRankingQueryServiceTest.kt`
+  - RED: 요청 타입의 최신 visible 스냅샷이 없으면 fallback job을 최대 3회까지 실행하고, 생성 후에도 `visibleFromAt > now`이면 직전 공개 스냅샷 또는 빈 배열을 응답하는 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.application.AudioRankingQueryServiceTest`
+  - GREEN: query service가 snapshot job service에 fallback을 위임하고 공개 응답 스키마를 유지한다.
+  - REFACTOR: fallback 실패는 구조화 로그/job 이력으로 추적하고 공개 응답에 fallback 여부를 추가하지 않는다.
+  - 기대 결과: 테스트 환경 초기 스냅샷 공백을 보강하되, 09:00 노출 정책은 깨지 않는다.
+
+### Phase 7: 통합 검증과 문서 정리
+
+- [ ] **Task 7.1: controller/facade/query 통합 테스트**
+  - Files:
+    - Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/content/ranking/adapter/in/web/AudioRankingControllerTest.kt`
+  - RED: `GET /api/v2/audio/rankings?type=RISING`이 `showRankChange`, `type`, `items[].contentId`, `rank`, `rankChange`, `isNew`를 반환하는 MockMvc 테스트를 작성한다.
+  - 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.content.ranking.adapter.in.web.AudioRankingControllerTest`
+  - GREEN: controller, facade, query service wiring을 완성한다.
+  - REFACTOR: 공개 response에 점수, 집계 기간, fallback 여부가 노출되지 않는지 확인한다.
+  - 기대 결과: 공개 API 계약이 end-to-end로 검증된다.
+
+- [ ] **Task 7.2: 문서와 DDL 최종 정합성 확인**
+  - Files:
+    - Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/prd.md`
+    - Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md`
+    - Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/create-content-ranking-tables.sql`
+  - TDD 예외 사유: 구현 완료 후 문서/DDL 정합성 확인 task이므로 신규 실패 테스트 작성 대상이 아니다.
+  - 대체 검증 방법:
+    - Run: `rg -n "visibleFromAt|visible_from_at|09:00:00|01:00:00|07:30:00|AudioRankingType" docs/20260623_메인_콘텐츠_랭킹_탭_API src/main/kotlin src/test/kotlin`
+    - Run: `./gradlew tasks --all`
+  - 기대 결과: PRD, 계획 문서, DDL, 코드가 같은 정책을 설명한다.
+
+- [ ] **Task 7.3: 전체 회귀 검증**
+  - Files:
+    - Verify: `build.gradle.kts`
+    - Verify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md`
+  - TDD 예외 사유: 전체 회귀 검증과 검증 기록 누적 task이므로 신규 실패 테스트 작성 대상이 아니다.
+  - 대체 검증 방법:
+    - Run: `./gradlew test --tests kr.co.vividnext.sodalive.v2.content.ranking.*`
+    - Run: `./gradlew test --tests kr.co.vividnext.sodalive.v2.api.content.ranking.*`
+    - Run: `./gradlew ktlintCheck`
+  - 기대 결과: 콘텐츠 랭킹 신규 테스트와 ktlint가 통과하고, 검증 결과가 이 문서 하단에 누적된다.
+
+### Phase 8: 다음 범위 크리에이터 랭킹 시간 정책 문서 시작점
+
+- [ ] **Task 8.1: 크리에이터 랭킹 시간 정책 변경을 별도 PRD 문서 수정으로 시작하도록 기록**
+  - Files:
+    - Verify: `docs/20260608_크리에이터_랭킹/prd.md`
+    - Verify: `docs/20260608_크리에이터_랭킹/plan-task.md`
+    - Verify: `docs/20260608_크리에이터_랭킹/create-ranking-tables.sql`
+    - Modify: `docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md`
+  - TDD 예외 사유: 이번 구현 범위 밖의 후속 작업 진입점을 문서화하는 task이므로 신규 실패 테스트 작성 대상이 아니다.
+  - 대체 검증 방법:
+    - Run: `rg -n "07:30|visibleFromAt|visible_from_at|ranking_type|크리에이터 랭킹" docs/20260608_크리에이터_랭킹 docs/20260623_메인_콘텐츠_랭킹_탭_API/plan-task.md`
+    - Run: `./gradlew tasks --all`
+  - 후속 작업 시작 지침:
+    - 다음 범위는 크리에이터 랭킹 PRD 문서 수정부터 시작한다.
+    - 현재 크리에이터 랭킹 스냅샷 생성 시간은 `@Scheduled(cron = "0 30 7 * * MON", zone = "Asia/Seoul")` 기준 매주 월요일 KST 07:30이다.
+    - 다음 범위에서는 크리에이터 랭킹도 집계 기준 시각 `월요일 00:00:00 KST`, 생성 시간 `월요일 01:00:00 KST` 후보, 노출 전환 시각 `월요일 09:00:00 KST`로 분리하는 정책을 PRD에 먼저 반영한다.
+    - 크리에이터 랭킹도 향후 다중 랭킹 타입 3개가 추가될 예정이므로 `creator_ranking_snapshot`과 `creator_ranking_snapshot_job`에 `ranking_type`, `visible_from_at` 추가가 필요한지 DDL 영향부터 검토한다.
+    - 크리에이터 랭킹 코드 변경은 별도 PRD와 별도 plan-task 문서가 준비된 뒤 진행한다.
+  - 기대 결과: 이번 콘텐츠 랭킹 구현 범위를 넘지 않으면서, 다음 범위의 첫 작업이 문서 수정부터 시작되도록 명확한 기록이 남는다.
+
+---
+
+## 검증 기록
+
+- 작성 시점: PRD 기반 구현 계획 문서를 신규 생성했다. 아직 구현 전이므로 task별 검증 기록은 없다.