Initial commit: Add project files

2026-08-02 05:15:36 +09:00
commit dcd1322d41
636 changed files with 122352 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Scheduler·시장캘린더·재처리 계약
+
+## Dispatcher 패턴
+
+Hangfire Recurring Job은 `model-operations-dispatcher-v1` 하나만 15분마다 실행한다. Dispatcher는 `evaluation.model_operation_schedule`에서 due row를 `FOR UPDATE SKIP LOCKED`로 lease하고 작업별 queue에 enqueue한다.
+
+- lease: 14분
+- batch limit: 50
+- schedule key: `operationCode + scopeKey + scheduleVersion`
+- request idempotency: `operationCode + scopeKey + scheduleVersion + due timestamp`
+- queue: q-evaluation, q-research, q-control, q-backfill
+
+이 구조는 시장별·모델별 recurring job 난립을 막고 schedule 변경 이력을 DB와 계약 파일에서 추적한다.
+
+## 거래일·DST 처리
+
+v12.4 코드 템플릿은 단순 cadence를 제공하지만 생산 구현은 `MarketCalendar`가 다음 조건을 판정해야 한다.
+
+- KRX, NYSE, NASDAQ의 휴장·반일장·DST
+- 시장 종가와 source data completeness
+- `published_at` 이후 최초 tradable session
+- 동일 session 재실행 idempotency
+- 장기 장애 후 catch-up 한도와 우선순위
+
+시장 캘린더 구현 전에는 시간대 hard-code를 생산 기준으로 사용하지 않는다. 이는 TD-042로 차단한다.
+
+## 오류 분류
+
+- `TRANSIENT`: 네트워크·DB 일시 오류. 승인 backoff로 제한 재시도.
+- `BUSINESS_HOLD`: 승인 Dataset/Model/Metric Definition 또는 표본 미충족. 재시도 폭주 금지.
+- `QUARANTINED`: PIT/DQ/VersionSet/무결성 위반. 수동 승인 전 후속작업 차단.
+- `POISON`: 동일 입력 반복 실패. dead-letter와 Runbook 실행.
+
+## 재처리
+
+재처리는 현재 row overwrite가 아니다. 새 request, observation, snapshot, proposal을 생성하고 before/after DatasetId와 content hash를 연결한다. 대량 backfill은 승인된 scope, through-watermark, dry-run diff가 있어야 한다.