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,51 @@
+# BE·FE·Hangfire 구현 표준
+
+## Backend
+
+새 `KArtSell.Modules.ModelOperations` 모듈은 다음 책임만 가진다.
+
+- Domain: cadence, automation mode, promotion evidence gate
+- Application: 승인 VersionSet 조회, 평가 request 생성
+- Infrastructure: Dapper schedule lease, request+Outbox transaction
+- Scheduling: 15분 dispatcher와 queue dispatch
+- Feature: 운영 계획 조회 API
+
+실제 Outcome, Drift, OOS, PBO/DSR 계산은 VS-18/19/20의 별도 handler로 구현한다. Scheduler 내부에 퀀트 수식을 넣지 않는다.
+
+## SOLID 적용
+
+- SRP: Dispatcher는 due job 배치만, evaluator는 계산만, reviewer는 승인만 수행한다.
+- OCP: `ModelOperationRegistry`와 operation handler 계약으로 작업 추가. reflection plugin framework는 금지한다.
+- LSP: evaluator 교체 시 PIT, 단위, window, idempotency contract test를 통과한다.
+- ISP: ContextReader, ScheduleRepository, RequestRepository를 좁은 port로 유지한다.
+- DIP: Domain은 Hangfire, Dapper, Npgsql, FastEndpoints를 참조하지 않는다.
+
+## Frontend
+
+`/ops/model-operations`는 운영 계획과 자동화 경계를 먼저 제공한다. 후속 화면은 다음 단위로 컴포넌트화한다.
+
+- AutomationBoundaryPanel
+- ModelOperationTable
+- MetricDefinitionBadge
+- DriftObservationPanel
+- ChampionChallengerComparison
+- FrozenEvidenceVersionSet
+- ImprovementProposalReview
+- PromotionGatePanel
+- RollbackDrillEvidence
+
+TanStack Query는 서버 상태, Pinia는 세션·권한·UI 선호, vue-router는 scope/cohort/window/filter를 소유한다. 모든 response는 Zod runtime validation 후 사용한다.
+
+## Hangfire
+
+- Dispatcher: q-control, 15분, 동시실행 금지
+- Evaluation: q-evaluation
+- Frozen research: q-research
+- Governance packet/drill: q-control
+- Revision replay: q-backfill
+
+연구 queue가 고객 추천 SLA를 침범하지 않도록 worker/connection/resource quota를 분리한다.
+
+
+### v12.4 request lifecycle audit clarification
+`evaluation.model_operation_request`는 실행 상태와 시각을 트랜잭션으로 갱신할 수 있는 lifecycle aggregate다. 모든 상태 전이는 `evaluation.model_operation_status_event`에 append-only로 기록하여 실행 이력과 재처리 증거를 보존한다.