docs(home): 응원 크리에이터 집계 기준을 문서화한다

docs/20260710_메인_홈_추천_응원크리에이터_스냅샷/prd.md

@@ -1,12 +1,13 @@
 # PRD: 메인 홈 추천 응원 크리에이터 스냅샷 수정
 
 ## 1. Overview
-메인 홈 추천 탭의 `CHEER_CREATOR` 스냅샷 생성과 조회를 전날 데이터 기반의 응원 점수로 수정하고, 스냅샷이 없을 때 홈 API가 동일 refresh 로직을 안전하게 재사용하도록 fallback 흐름을 보강한다.
+메인 홈 추천 탭의 `CHEER_CREATOR` 스냅샷 생성과 조회를 최근 7일 데이터 기반의 응원 점수로 수정하고, 스냅샷이 없을 때 홈 API가 동일 refresh 로직을 안전하게 재사용하도록 fallback 흐름을 보강한다.
 
 ---
 
 ## 2. Problem
-- 기존 `CHEER_CREATOR` 산식은 최근 7일 데이터를 기반으로 하며, 후원 금액 가중치와 신규 부스트 값이 이번 요구사항과 다르다.
+- 기존 `CHEER_CREATOR` 스냅샷은 전날 KST 하루 데이터만 사용해, 인기 커뮤니티와 동일한 최근 7일 집계 기준과 다르다.
+- 기존 후원 집계는 `CanUsage.CHANNEL_DONATION`만 대상으로 하며, 일반 후원 `CanUsage.DONATION`을 함께 반영하지 않는다.
 - 현재 일괄 refresh와 홈 API fallback refresh가 섹션별로 동일한 생성 로직을 공유하지 않으면 산식 drift가 발생할 수 있다.
 - 스냅샷이 없는 초기 배포, 운영 데이터 삭제, 배치 실패 상황에서 홈 조회가 매 요청마다 무거운 집계를 중복 실행하면 API 지연과 DB 부하가 커질 수 있다.
 - 집계 산식이 추천 노출 순서를 직접 바꾸므로 DB-side 계산과 Kotlin-side 계산 중 어떤 방식을 선택하더라도 산식/부스트 경계값 테스트가 필요하다.
@@ -14,8 +15,8 @@
 ---
 
 ## 3. Goals
-- `CHEER_CREATOR` 스냅샷은 전날 KST 하루 데이터를 기반으로 생성한다.
-- 응원 점수 산식을 `((채널 후원 금액 * 0.45) + (팬Talk 수 * 0.30) + (채널 후원 수 * 0.10)) * 신규 부스트`로 변경한다.
+- `CHEER_CREATOR` 스냅샷은 인기 커뮤니티와 동일하게 스냅샷 생성 시점 기준 최근 7일 데이터를 기반으로 생성한다.
+- 응원 점수 산식을 `((후원 금액 * 0.45) + (팬Talk 수 * 0.30) + (후원 수 * 0.10)) * 신규 부스트`로 변경한다.
 - 신규 부스트는 크리에이터 데뷔일 기준 10일 이내 1.15, 20일 이내 1.10, 30일 이내 1.05, 그 외 1.0을 적용한다.
 - 스케줄러 refresh와 fallback refresh는 동일한 `CHEER_CREATOR` refresh 로직을 재사용한다.
 - 스냅샷이 없을 때 fallback refresh는 lock, double-check, single-flight 대기로 중복 refresh를 방지한다.
@@ -35,14 +36,14 @@
 ---
 
 ## 5. Target Users
-- 회원/비회원: 메인 홈 추천 탭에서 전날 응원 반응이 많았던 크리에이터를 발견하는 사용자
+- 회원/비회원: 메인 홈 추천 탭에서 최근 7일 응원 반응이 많았던 크리에이터를 발견하는 사용자
 - 앱 클라이언트: 기존 응답 계약을 유지한 채 `CHEER_CREATOR` 추천 순서만 변경된 결과를 받는 클라이언트
-- 운영자: 전날 후원/팬Talk 반응이 추천 노출에 반영되는지 확인해야 하는 운영 담당자
+- 운영자: 최근 7일 후원/팬Talk 반응이 추천 노출에 반영되는지 확인해야 하는 운영 담당자
 
 ---
 
 ## 6. User Stories
-- 사용자는 메인 홈 추천 탭에서 전날 응원이 많았던 크리에이터를 우선 보고 싶다.
+- 사용자는 메인 홈 추천 탭에서 최근 7일 응원이 많았던 크리에이터를 우선 보고 싶다.
 - 사용자는 후원 금액뿐 아니라 팬Talk와 후원 참여 횟수도 함께 반영된 추천을 보고 싶다.
 - 사용자는 신규 크리에이터가 일정 기간 동안 적절한 노출 기회를 받기를 기대한다.
 - 앱 클라이언트는 스냅샷이 없는 상황에서도 홈 API가 실패하지 않고 안정적으로 빈 배열 또는 생성된 스냅샷을 받기를 원한다.
@@ -56,11 +57,11 @@
 
 #### Requirements
 - `CHEER_CREATOR` 점수는 아래 산식으로 계산한다.
-  - `score = ((channelDonationAmount * 0.45) + (fanTalkCount * 0.30) + (channelDonationCount * 0.10)) * newBoost`
-- `channelDonationAmount`는 집계 기간 안에 발생한 채널 후원 금액 합계다.
-- `channelDonationCount`는 집계 기간 안에 발생한 채널 후원 건수다.
-- 채널 후원 수는 `UseCanCalculate.useCan`이 같은 row를 1개 후원 이벤트로 보고 중복 제거해 계산한다.
-- 채널 후원은 기존 요구사항과 동일하게 `CanUsage.CHANNEL_DONATION`이며, 환불/미수령/비정상 상태는 기존 채널 후원 집계 제외 조건을 유지한다.
+  - `score = ((donationAmount * 0.45) + (fanTalkCount * 0.30) + (donationCount * 0.10)) * newBoost`
+- `donationAmount`는 집계 기간 안에 발생한 채널 후원과 일반 후원 금액 합계다.
+- `donationCount`는 집계 기간 안에 발생한 채널 후원과 일반 후원 건수다.
+- 후원 수는 `UseCanCalculate.useCan`이 같은 row를 1개 후원 이벤트로 보고 중복 제거해 계산한다.
+- 후원은 `CanUsage.CHANNEL_DONATION`과 일반 후원 `CanUsage.DONATION`을 포함하며, 환불/미수령/비정상 상태는 기존 후원 집계 제외 조건을 유지한다.
 - `fanTalkCount`는 집계 기간 안에 생성된 활성 팬Talk 수다.
 - 팬Talk 수는 `CreatorCheers.isActive == true`인 row 수로 계산한다.
 - 팬Talk는 기존 `CreatorCheers` 또는 현재 구현의 `creator_cheers` 기반 데이터를 의미한다.
@@ -69,20 +70,20 @@
 - 최종 저장 수는 기존 홈 노출 안정성을 위해 `CHEER_CREATOR` 최대 16개를 유지한다.
 
 #### Edge Cases
-- `channelDonationAmount`, `fanTalkCount`, `channelDonationCount`가 모두 0인 크리에이터는 스냅샷 후보에서 제외한다.
+- `donationAmount`, `fanTalkCount`, `donationCount`가 모두 0인 크리에이터는 스냅샷 후보에서 제외한다.
 - 후원 금액은 없지만 팬Talk가 있으면 산식에 따라 점수를 계산한다.
-- 팬Talk는 없지만 채널 후원이 있으면 산식에 따라 점수를 계산한다.
+- 팬Talk는 없지만 채널 후원 또는 일반 후원이 있으면 산식에 따라 점수를 계산한다.
 - 비활성 크리에이터, 차단 필터에 의해 조회 시 제외되는 크리에이터는 최종 홈 응답에서 제외한다.
 - 스냅샷에는 존재하지만 조회 시점에 크리에이터가 비활성화된 경우 응답에서 제외한다.
 
-### Feature B. 전날 데이터 기반 집계 기간
+### Feature B. 최근 7일 데이터 기반 집계 기간
 
 #### Requirements
-- 점수 입력값은 전날 KST 하루 데이터만 사용한다.
-- 전날 기준은 KST 기준 전일 00:00:00 이상, 다음날 00:00:00 미만의 half-open 범위로 정의한다.
+- 점수 입력값은 인기 커뮤니티와 동일하게 스냅샷 생성 시점 기준 최근 7일 데이터를 사용한다.
+- 최근 7일 기준은 KST 기준 전날을 포함한 7일의 시작 시각 이상, 다음날 00:00:00 미만의 half-open 범위로 정의한다.
 - 운영 DB 시간이 UTC 기준이면, 실제 조회는 `windowStartUtc <= createdAt < windowEndExclusiveUtc`로 변환해 사용한다.
 - `snapshotAt`은 해당 KST 전날의 종료 시각을 UTC로 변환한 `windowEndExclusiveUtc.minusSeconds(1)`을 사용한다.
-- 스케줄러가 KST 06:00에 실행되면 실행일 전날 KST 일자를 집계 대상으로 삼는다.
+- 스케줄러가 KST 06:00에 실행되면 실행일 전날 KST 일자를 포함한 최근 7일을 집계 대상으로 삼는다.
 - 기존 코드에 남아 있는 `created_at <= :snapshotAt` 방식은 이번 범위에서 half-open end-exclusive 조건으로 맞춘다.
 
 #### Edge Cases
@@ -180,7 +181,7 @@
 - DB-side scoring을 유지하는 경우 Kotlin 단에는 산식 parity 검증용 정책 함수를 두고, DB expression과 같은 상수를 공유한다.
 - Kotlin-side scoring으로 변경하는 경우 DB에서 필요한 원천 metric을 정확히 집계하고, service에서 최종 점수/정렬/limit을 적용한다. 이 경우 후보 전체를 메모리에 올리는 비용과 데이터량을 구현 계획에서 검토한다.
 - 기본 권장안은 현재 구조와 성능 특성을 유지하는 DB-side exact scoring이다. 다만 산식/부스트 계산은 Kotlin 정책 테스트로 검증 가능한 형태를 둔다.
-- 시간 범위는 KST 전날을 UTC half-open window로 변환하는 `RecommendationSnapshotWindowPolicy`를 재사용한다.
+- 시간 범위는 인기 커뮤니티와 동일한 최근 7일 UTC half-open window를 반환하는 `RecommendationSnapshotWindowPolicy`를 재사용한다.
 - 신규 DDL은 만들지 않는 것을 기본으로 한다. 불가피하게 필요하면 운영 DB 반영용 SQL 문서는 MySQL 기준으로 별도 작성한다.
 
 ---
@@ -190,7 +191,7 @@
 - `CHEER_CREATOR` 스냅샷 최종 저장 수
 - fallback refresh 실행/성공/실패/timeout 로그
 - fallback refresh lock 획득 성공/실패 로그
-- `channelDonationAmount`, `fanTalkCount`, `channelDonationCount` 입력값 분포
+- `donationAmount`, `fanTalkCount`, `donationCount` 입력값 분포
 - empty snapshot marker 저장 횟수
 - 홈 API `CHEER_CREATOR` 섹션 빈 응답 비율
 - 홈 API fallback refresh 대기 시간
@@ -203,8 +204,8 @@
 ---
 
 ## 11. Decisions
-- 채널 후원 금액은 `use_can_calculate.can` 값을 그대로 사용한다.
-- 채널 후원 수는 `UseCanCalculate.useCan`이 같은 row를 1개 후원 이벤트로 보고 중복 제거한다.
+- 후원 금액은 `use_can_calculate.can` 값을 그대로 사용한다.
+- 후원 수는 `UseCanCalculate.useCan`이 같은 row를 1개 후원 이벤트로 보고 중복 제거한다.
 - 팬Talk 수는 `CreatorCheers.isActive == true`인 row 수로 계산한다.
 - 빈 결과 marker 정책은 다른 스냅샷 섹션에도 확장하는 것이 맞지만, 이번 구현 범위에서는 `CHEER_CREATOR`에만 적용한다.