klaus/sodalive-backend-spring-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(ranking): 스냅샷 lock 계획을 기록한다

Browse Source
This commit is contained in:
Klaus
2026-06-08 20:19:24 +09:00
parent 7fee004e7f
commit 8ab4d0ae84
2 changed files with 25 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/20260608_크리에이터_랭킹/plan-task.md
View File

@@ -16,7 +16,9 @@
- 구현 패키지: `kr.co.vividnext.sodalive.v2.ranking`
- 집계 기간: 조회/스냅샷 생성 시점 기준 KST 지난 주 월요일 00:00:00 이상, 이번 주 월요일 00:00:00 미만
- DB 조회 기간: KST 집계 기간을 UTC 기준 `LocalDateTime` 또는 프로젝트 표준 시간 타입으로 변환한 기간
- 스냅샷 생성 스케줄 후보: 매주 월요일 KST 06:00, `@Scheduled(cron = "0 0 6 * * MON", zone = "Asia/Seoul")`
- 스냅샷 생성 스케줄 후보: 매주 월요일 KST 07:30, `@Scheduled(cron = "0 30 7 * * MON", zone = "Asia/Seoul")`
- 다중 서버 인스턴스에서 스냅샷 스케줄러가 중복 실행되지 않도록 기존 Redisson 기반 분산 lock을 사용한다.
- 랭킹 스냅샷 lock key는 `lock:creator-ranking-snapshot-refresh`로 고정하고, lock 획득 실패 인스턴스는 정상 skip한다.
- 조회 API는 원천 데이터 실시간 계산 fallback을 두지 않는다.
- API 응답은 `showRankChange`, `items[].rank`, `items[].rankChange`, `items[].isNew`, `items[].creatorId`, `items[].nickname`, `items[].profileImageUrl`만 포함한다.
- API 응답에는 집계 기간 날짜와 `finalScore`를 포함하지 않는다.
@@ -193,16 +195,26 @@
- REFACTOR: service는 계산 흐름만 담당하고 DB 조회 조건/저장 구현은 port 뒤로 숨긴다.
- 기대 결과: 스냅샷 저장 대상이 “20위 초과 점수 + 20위 동점 전체” 규칙을 만족한다.
- [x] **Task 4.2: 매주 월요일 06:00 KST 스케줄러 추가**
- [x] **Task 4.2: 매주 월요일 07:30 KST 스케줄러 추가**
- Files:
- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/ranking/adapter/out/scheduler/CreatorRankingSnapshotScheduler.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/ranking/application/CreatorRankingSnapshotRefreshServiceTest.kt`
- RED: scheduler method에 `@Scheduled(cron = "0 0 6 * * MON", zone = "Asia/Seoul")`가 선언되어 있는지 reflection 테스트를 작성한다.
- RED: scheduler method에 `@Scheduled(cron = "0 30 7 * * MON", zone = "Asia/Seoul")`가 선언되어 있는지 reflection 테스트를 작성한다.
- 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.ranking.application.CreatorRankingSnapshotRefreshServiceTest`
- GREEN: 스케줄러가 `CreatorRankingSnapshotRefreshService.refreshLastCompletedWeek()`를 호출하도록 구현한다.
- REFACTOR: 스케줄러에는 기간/점수/DB 로직을 두지 않는다.
- 기대 결과: 주간 스냅샷 생성 트리거가 KST 기준으로 고정된다.
- [x] **Task 4.3: 주간 스냅샷 스케줄러 Redisson lock 적용**
- Files:
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/ranking/adapter/out/scheduler/CreatorRankingSnapshotScheduler.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/ranking/application/CreatorRankingSnapshotRefreshServiceTest.kt`
- RED: Redisson lock 획득 성공 시 `CreatorRankingSnapshotRefreshService.refreshLastCompletedWeek()`를 1회 호출하고, 획득 실패 시 호출하지 않는 테스트를 작성한다. lock key가 `lock:creator-ranking-snapshot-refresh`인지도 검증한다.
- 실패 확인: `./gradlew test --tests kr.co.vividnext.sodalive.v2.ranking.application.CreatorRankingSnapshotRefreshServiceTest`
- GREEN: 기존 `RedissonClient` bean을 스케줄러에 주입하고 `tryLock`으로 lock을 획득한 인스턴스만 refresh service를 호출한다. lock 획득 실패는 정상 skip으로 처리한다.
- REFACTOR: DB 기반 scheduler lock 테이블은 추가하지 않고, 기존 `AudioContentReleaseScheduledTask`의 Redisson lock 패턴을 참고하되 스케줄러에는 lock 획득/해제와 service 호출만 둔다.
- 기대 결과: 여러 서버 인스턴스에서 같은 cron이 동시에 실행돼도 클러스터 전체에서 한 인스턴스만 주간 랭킹 스냅샷을 생성한다.
### Phase 5: 조회 서비스, 순위 변화, 차단 마스킹
- [ ] **Task 5.1: 최신/직전 스냅샷 기반 조회 서비스 구현**
@@ -289,7 +301,7 @@
- Feature E: Task 1.2, Task 3.4, Task 4.1에서 최종 팔로우 수와 `createdAt`/`updatedAt` 기반 팔로우 증가 수를 검증한다.
- Feature F: Task 1.2, Task 4.1, Task 5.1에서 raw value 최종 점수, 1점 미만 제외, 20위 동점 후보 저장, 동점 랜덤 조회를 검증한다.
- Feature G: Task 5.1, Task 5.2, Task 6.1, Task 6.2에서 API endpoint, 응답 스키마, 순위 변화, 신규 진입, 차단 마스킹을 검증한다.
- Feature H: Task 2.1, Task 2.2, Task 4.1, Task 4.2에서 주간 스냅샷 저장과 스케줄을 검증한다.
- Feature H: Task 2.1, Task 2.2, Task 4.1, Task 4.2, Task 4.3에서 주간 스냅샷 저장, 스케줄, 클러스터 단일 실행 lock을 검증한다.
- Feature I: 모든 task에서 `v2.ranking` 패키지 경계를 유지하고, Task 6.1에서 endpoint만 home 하위로 둔다.
---
@@ -318,4 +330,7 @@
- 2026-06-08: Phase 4 포맷 검증: `./gradlew ktlintCheck` 실행 결과 `BUILD SUCCESSFUL in 22s`를 확인했다.
- 2026-06-08: Phase 4 전체 회귀 검증: `./gradlew test` 실행 결과 `BUILD SUCCESSFUL in 56s`를 확인했다.
- 2026-06-08: Phase 4 reviewer gate: 스냅샷 생성 서비스/스케줄러/테스트/문서 변경에 대해 strict review를 수행했고 `PASS` 판정을 확인했다.
- 2026-06-08: Task 4.3 및 07:30 스케줄 변경 focused 검증: `./gradlew test --tests kr.co.vividnext.sodalive.v2.ranking.application.CreatorRankingSnapshotRefreshServiceTest` 실행 결과 `BUILD SUCCESSFUL in 16s`를 확인했다.
- 2026-06-08: Task 4.3 ranking 범위 회귀 검증: `./gradlew test --tests 'kr.co.vividnext.sodalive.v2.ranking.*'` 실행 결과 `BUILD SUCCESSFUL in 18s`를 확인했다.
- 2026-06-08: Task 4.3 포맷 검증: `./gradlew ktlintCheck` 실행 결과 `BUILD SUCCESSFUL in 26s`를 확인했다.
- 후속 구현 중 각 task 완료 시 실행 명령, 목적, 결과를 이 섹션에 누적한다.