docs(ranking): 스냅샷 운영 계획을 갱신한다

docs/20260608_크리에이터_랭킹/prd.md

@@ -27,9 +27,9 @@
 ---
 
 ## 4. Non-Goals
-- 이번 PRD에서는 관리자 화면 신규 개발을 포함하지 않는다.
+- 이번 PRD에서는 별도 관리자 화면 신규 개발을 포함하지 않는다. 단, 기존 관리자 영역에서 호출할 수 있는 스냅샷 수동 생성/재시도용 관리자 전용 API는 포함한다.
 - 크리에이터 랭킹 산식의 머신러닝 모델화, 개인화, A/B 테스트는 포함하지 않는다.
-- 실시간 랭킹 또는 현재 주 진행 중 랭킹은 포함하지 않는다.
+- 실시간 랭킹 또는 현재 주 진행 중 랭킹은 포함하지 않는다. 단, 스냅샷 테이블이 완전히 비어 있는 초기 상태에서만 제한적으로 원천 데이터 fallback 집계를 시도할 수 있다.
 - 기존 공개 API 스키마를 임의 변경하지 않는다.
 - 랭킹 결과 수동 보정 기능은 포함하지 않는다.
 - 점수 산식의 가중치를 관리자에서 동적으로 수정하는 기능은 포함하지 않는다.
@@ -188,11 +188,15 @@
 - 조회자와 크리에이터 사이에 차단 관계가 있으면 랭킹 row는 유지하되 응답의 크리에이터 id는 `0`, 닉네임은 빈 문자열로 내려준다.
 - 차단 관계가 있는 크리에이터의 프로필 이미지는 기본 이미지 URL로 내려주고, 이동 대상 id는 `0`으로 내려준다.
 - 인증 사용자 조건이 필요하지 않은 공개 조회를 기본으로 하되, 차단 마스킹 정책은 인증 사용자에게 적용한다.
+- 조회 API는 스냅샷 기반 응답을 기본으로 하며, 공개 API 응답 스키마는 fallback 여부와 관계없이 변경하지 않는다.
+- 스냅샷 테이블이 완전히 비어 있는 초기 상태에서만 조회 API가 제한적으로 원천 데이터 fallback 집계를 시도할 수 있다.
+- 스냅샷 테이블에 과거 스냅샷이 하나라도 있으면 원천 데이터 fallback을 시도하지 않고 최신 완료 주차 스냅샷 기준으로 응답한다.
 
 #### Edge Cases
 - 최종 점수 1점 이상인 랭킹 후보가 20명 미만이면 가능한 만큼만 내려준다.
 - 랭킹 계산 결과가 없으면 빈 배열로 성공 응답한다.
-- 최신 완료 주차 스냅샷이 없으면 빈 배열로 성공 응답한다.
+- 최신 완료 주차 스냅샷이 없고 스냅샷 테이블도 완전히 비어 있으면 제한적 원천 데이터 fallback 집계를 시도한 뒤 결과를 응답한다.
+- 스냅샷 테이블에 과거 스냅샷이 하나라도 있으면 원천 데이터 fallback을 시도하지 않고 기존 최신 완료 주차 스냅샷 기준 응답을 유지한다.
 - 직전 완료 주차 스냅샷이 없으면 `showRankChange`는 `false`로 내려주고, 각 item의 `rankChange`는 `null`, `isNew`는 `false`로 내려준다.
 
 ### Feature H. 주간 랭킹 스냅샷
@@ -214,11 +218,18 @@
 - 주간 랭킹 스냅샷 lock key는 `lock:creator-ranking-snapshot-refresh`를 사용하며, lock 획득 실패 인스턴스는 스냅샷 생성을 skip한다.
 - 같은 집계 기간에 대해 스냅샷을 재생성할 수 있어야 하며, 재생성 시 기존 같은 기간 스냅샷을 중복 노출하지 않는다.
 - 조회 API는 최신 완료 주차의 스냅샷을 기준으로 응답한다.
+- 스냅샷 생성 직전 집계 시작/종료 시각을 포함한 job 이력을 생성하고, 작업 완료 후 성공/실패 상태와 처리 결과를 기록한다.
+- 스케줄러로 실행되는 주간 스냅샷 생성도 job 이력으로 기록한다.
+- 운영자는 관리자 전용 API를 통해 날짜 범위를 직접 선택해 스냅샷 생성 job을 생성할 수 있어야 한다.
+- 실패한 스냅샷 생성 job은 관리자 전용 재시도 API로 재시도할 수 있어야 하며, 기존 관리자 job 패턴과 같이 실패 상태 job을 대기 상태로 되돌려 worker가 다시 처리하도록 한다.
+- 관리자 전용 job 목록 API는 날짜 범위, 실행 트리거, 상태, 실패 사유, 재시도 가능 여부를 확인할 수 있어야 한다.
 
 #### Edge Cases
-- 최신 완료 주차 스냅샷이 없으면 빈 배열로 성공 응답하고, 장애 추적용 로그를 남긴다.
+- 최신 완료 주차 스냅샷이 없고 스냅샷 테이블이 완전히 비어 있으면 제한적 원천 데이터 fallback 집계를 시도하고, fallback 성공/실패를 장애 추적용 로그로 남긴다.
+- 스냅샷 테이블에 과거 스냅샷이 하나라도 있으면 원천 데이터 fallback을 시도하지 않고 최신 완료 주차 스냅샷 기준 응답을 유지한다.
 - 스냅샷 생성 중 일부 원천 집계가 실패하면 해당 주차 스냅샷 저장을 실패 처리하고 부분 결과를 공개하지 않는다.
 - Redisson lock 획득 실패는 다른 인스턴스가 같은 작업을 수행 중인 정상 skip으로 처리하고, 스냅샷 생성 실패로 집계하지 않는다.
+- 실패 job 재시도 API는 실패 상태 job만 대상으로 하며, 이미 대기/처리 중/성공 상태인 job은 재시도 대상으로 변경하지 않는다.
 
 ### Feature I. 랭킹 계산 컴포넌트 분리
 
@@ -236,7 +247,7 @@
 
 #### Edge Cases
 - 캐시가 추가되더라도 산식 테스트는 캐시와 분리된 순수 정책 테스트로 유지한다.
-- 조회 API는 원천 데이터 실시간 계산 fallback을 두지 않는다.
+- 조회 API는 스냅샷 기반 응답을 기본으로 하며, 스냅샷 테이블이 완전히 비어 있는 초기 상태를 제외하고 원천 데이터 실시간 계산 fallback을 두지 않는다.
 
 ---
 
@@ -260,6 +271,9 @@
 - 랭킹 계산 소요 시간
 - 주간 스냅샷 생성 성공/실패 수
 - 주간 스냅샷 생성 지연 시간
+- 스냅샷 job 상태별 수와 실패 job 재시도 수
+- 관리자 수동 생성 job 요청 수와 성공/실패 수
+- 스냅샷 테이블 완전 공백 fallback 시도/성공/실패 수
 - 랭킹 후보 크리에이터 수
 - 최종 점수 1점 미만으로 제외된 크리에이터 수
 - 랭킹 조회 성공/실패 로그 수