통계 갱신 dirty 이벤트(Stats Refresh Dirty Events)
한국어 번역본
이 문서는 원문(영어)의 한국어 번역이다. 정본은 원문이며, 계약·게이트 판단이 갈리면 원문을 따른다. 원문: docs/data/stats-refresh-dirty-events.md
이 문서는 증분 통계 갱신(incremental stats refresh) 계획의 2-1 단계를 정의한다. 즉 어떤 이벤트가 구체화된(materialized) 사용자 종목 통계를 낡게(stale) 만드는가이다.
완료 운동 쓰기는 이제 dirty 범위를 enqueue하고, 구체화된 통계 갱신이 끝나기 전에 반환한다. 인증된 앱은 자신의 큐를 백그라운드에서 드레인하며, 데이터베이스 cron 잡이 영속 폴백 역할을 한다. 임포트 경로와 관리자 수리 경로는 큐에 넣은 작업을 여전히 인라인으로 처리할 수 있다. 아래의 이벤트 정의는 그 경로들이 공유하는 어휘이며, 이벤트 이름이 SQL 함수, Edge Function, 테스트 전반에서 안정적으로 유지되도록 public.stats_refresh_event_types에 저장된다.
dirty 범위 계약
모든 dirty 이벤트는 다음 최소 페이로드로 귀결되어야 한다.
user_id: 영향을 받은 훈련 데이터의 소유자.from_date: 통계가 변했을 수 있는 가장 이른 완료 세션 날짜.exercise_ids: 영향을 받은 종목 id. placeholder id가 canonical 행에서 아직 사용 중이라면 포함한다.event_type:public.stats_refresh_event_types의 id 중 하나.
from_date는 의도적으로 보수적이다. 날짜가 움직일 수 있는 경우에는 least(old.date, new.date)를 사용한다. 행을 삭제하는 경우에는 삭제 전에 이전 세션 날짜와 종목 id를 확보한다. 종목 id가 바뀌는 경우에는 이전 id와 새 id를 모두 포함한다.
이벤트 타입
| 이벤트 | 소스 | dirty 범위 |
|---|---|---|
session_created | sessions insert | 새 완료 세션 날짜, 해당 세션의 모든 종목 |
session_updated | sessions update | least(old.date, new.date), 이전 및 새 완료 세션 종목 |
session_deleted | sessions delete | 삭제 전에 확보한 삭제된 세션 날짜, 삭제된 세션의 종목 |
session_exercise_created | session_exercise_part insert | 부모 완료 세션 날짜, 삽입된 종목 id |
session_exercise_deleted | session_exercise_part delete | 삭제 전에 확보한 부모 완료 세션 날짜, 삭제된 종목 id |
session_exercise_exercise_changed | session_exercise_part update | 부모 완료 세션 날짜, 이전 및 새 종목 id |
exercise_set_created | exercise_set_part insert | 부모 완료 세션 날짜, 부모 종목 id |
exercise_set_updated | exercise_set_part update | 부모 완료 세션 날짜, 부모 종목 id |
exercise_set_deleted | exercise_set_part delete | 삭제 전에 확보한 부모 완료 세션 날짜, 부모 종목 id |
placeholder_resolved | exercise_external_mappings resolve | 해당 placeholder를 사용하는 가장 이른 완료 세션, placeholder id와 canonical id |
wodup_import_materialized | wodup_import_batches bulk | 배치에서 가장 이르게 임포트된 세션, 배치 내 모든 매핑 id와 placeholder id |
통계에 영향을 주는 변경
다음 변경은 구체화된 통계를 dirty로 만든다.
- 세션이 완료 상태가 되거나, 완료 상태로 생성되거나, 삭제되거나, 날짜·상태·제목이 바뀐다.
- 세션 종목이 추가되거나, 삭제되거나,
exercise_id가 바뀐다. - 세트가 추가되거나 삭제된다.
- 세트에서 통계에 사용되는 필드가 바뀐다:
reps,load,set_type, 또는position. - placeholder 종목이 canonical 종목으로 해소된다.
- Wodup 임포트 배치가 세션들을 canonical 테이블로 구체화한다.
다음 변경은 오늘 기준으로 통계를 dirty로 만들지 않는다.
- 세션, 세션 종목, 세트에 대한 사용자 메모.
rest_seconds,free_rest. 단, 앞으로 통계가 이들을 사용하기 시작하면 예외다.- UI 전용 라벨이나 캐시된 표시 메타데이터.
앞으로 제품 로직이 dirty가 아닌 이 필드들 중 하나를 볼륨, PR, 강도 계산에 사용하기 시작한다면, 계산을 바꾸기 전에 그 필드를 이 계약에 추가한다.
큐 테이블
2-2 단계에서 public.user_exercise_stats_refresh_jobs를 추가하며, event_type은 public.stats_refresh_event_types(id)를 참조한다. 큐 테이블 계약은 /data/stats-refresh-jobs를 참고한다.
처리 계약
병합, enqueue 전용 쓰기, 워커, cron 복구 동작은 /data/stats-refresh-jobs를 참고한다.