Phase 3 KPI 계약 상수 분리

apps/api/app/services/phase3_kpi_contract.py

@@ -0,0 +1,40 @@
+"""Phase 3 KPI evidence report contract constants."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+PREPOST_MEASURE_NAMES = (
+    "self_efficacy",
+    "skill_proficiency",
+    "training_satisfaction",
+)
+PREPOST_TIMEPOINTS = ("pre", "post")
+PHASE3_KPI_METRICS = (
+    "embedding_consistency",
+    "hallucination_rate",
+    "icc",
+    "inter_rater_kappa",
+    "pilot_completion",
+    "self_efficacy_prepost",
+    "session_completion",
+    "sus",
+    "top1",
+)
+KPI_METRIC_STATUSES = (
+    "computed_prepost",
+    "design_pending",
+)
+KpiMetricStatus = Literal["computed_prepost", "design_pending"]
+KPI_METRIC_REQUIRED_KEYS = {
+    "denominator",
+    "method",
+    "numerator",
+    "pass",
+    "source_files",
+    "status",
+    "threshold",
+    "value",
+}
+PREPOST_CSV_PATH = "02-measures/prepost_measures.csv"
+KPI_REPORT_PATH = "02-measures/kpi_report.json"

apps/api/app/test_phase3_artifact_checker.py

@@ -79,7 +79,7 @@ class Phase3ArtifactCheckerTests(unittest.TestCase):
                 "method": "fixture",
                 "source_files": ["fixture"],
             }
-            for name in checker.KPI_METRICS
+            for name in checker.PHASE3_KPI_METRICS
         }
         write_text(
             root / "02-measures" / "kpi_report.json",

apps/api/app/test_phase3_kpi_export.py

@@ -15,18 +15,7 @@ from app.services.phase3_kpi_export import (
     write_kpi_report,
     write_prepost_csv,
 )
-
-
-REQUIRED_METRIC_KEYS = {
-    "denominator",
-    "method",
-    "numerator",
-    "pass",
-    "source_files",
-    "status",
-    "threshold",
-    "value",
-}
+from app.services.phase3_kpi_contract import KPI_METRIC_REQUIRED_KEYS
 
 
 def fixture_rows():
@@ -134,7 +123,7 @@ class Phase3KpiExportTests(unittest.TestCase):
         self.assertEqual(report["cohort_size"], 2)
         self.assertTrue(set(PHASE3_KPI_METRICS).issubset(report["metrics"]))
         for metric in report["metrics"].values():
-            self.assertTrue(REQUIRED_METRIC_KEYS.issubset(metric))
+            self.assertTrue(KPI_METRIC_REQUIRED_KEYS.issubset(metric))
         self_efficacy = report["metrics"]["self_efficacy_prepost"]
         self.assertFalse(self_efficacy["pass"])
         self.assertEqual(self_efficacy["status"], "computed_prepost")