Guidant AI v1.3.1 Release Note

1. 概述

v1.3.1 把外部 Python 報表專案（validate.py / gen_ao_adjudication.py / gen_summary.py）的分析報表能力整進系統，並讓每次分類 run 的結果落 DB（這階段 DB + Drive 兩存）。

對正式環境的一般使用者沒有可見變化 —— 報表/歷史/選模型/費用這些都是調校期 / Admin 才開放的功能，由 VITE_DEV_MODE 控制，STG/PRD build 預設關閉。唯一一律生效的是「run 結果落 DB」（BE 旁路寫入，不影響既有 Drive 流程）。

仍屬實驗階段（同 v1.3.0）：僅支援 cmmc-l1、報表為 v0 即時計算。

2. 重點功能（FR-031）

2.1 run 結果落 DB

• 新表 compliance.evidence_classification_runs（JSONB 鏡像 report_original / state + container_log）。
• 既有 _finalize_drive_output / put_state / archive_run 旁路寫 DB（失敗不回滾 Drive）；舊 run 首次讀報表時 lazy 從 Drive 回填。
• 附帶解掉 v0「restart 後 in-memory 反查 tenant 失效」。

2.2 兩份分析報表（DEV/Admin-only）

• 驗證報表（量化）：AO/控制項層級召回精確、缺漏/多餘四級、未分類三類診斷、Docker log、成本。
• 各 AO 誰對誰錯（質化）：以固定 CANON 正解判 User/AI（標錯/多放/超範圍 + 逐 AO）。
• FE 兩頁照外部 script HTML 1:1 重刻版面（KPI 卡/彩色 chip/召回長條/巢狀折疊）。

2.3 歷史分類紀錄分析（跨批總表，DEV/Admin-only）

• 一列一 run 並排比較模型/門檻/控制召回精確/AI多放/未分類/成本，標出最佳（控制精確最高）。
• 點開自動掃該 AP 的 Drive run folders 回填進 DB。

2.4 正解匯入（ground truth）

• 新表 compliance.evidence_classification_ground_truth（per-tenant {檔名:[ao_id]}）+ POST /classification-ground-truth。
• 報表的「User 正解」優先用匯入正解（否則審閱後 state）→ 即使未審閱也能出完整報表。
• 操作 + 無正解決策見 docs/api/evidence-classification/ground-truth-operations.md。

2.5 VITE_DEV_MODE 開關

• src/config/featureFlags.js；gate 選模型 / 歷史分析 / 兩報表入口 / Token費用提示。
• .env.development=true、.env.staging/.env.production=false。

3. DB Migration（部署必跑）

兩個 migration（非破壞性，只 CREATE 新表 + GRANT）：

scripts/sql/2026-05-31_fr031_evidence_classification_runs.sql
scripts/sql/2026-05-31_fr031_evidence_classification_ground_truth.sql

用 cmmgr 套（cm_app 受 RLS）。DEV / STG / POC 已套。各環境若要報表完整需另灌該 tenant 正解（見 runbook）。

4. 部署順序

1. DB：套兩個 migration（已對 DEV/STG/POC 完成）。
2. BE：部署 + 重啟（新報表/summary 端點 + run 落 DB + 自動回填）。
3. FE：rebuild；對外環境確認 VITE_DEV_MODE=false。
4. （要報表完整）灌該 tenant 正解。

5. 相依套件 / 版號

• jedi-* 無異動；BE / FE 皆無新第三方依賴。
• BE pyproject.toml 1.3.0 → 1.3.1；FE package.json 對齊 1.3.1。

6. 已知 follow-up

1. 「把審閱修正後的 run 一鍵設為正解」功能（目前正解只能 API/手動灌）。
2. CANON 動態化 / 規則表（目前逐檔寫死亞航 63 檔，換資料集失效）—— design D6 延後。
3. 報表頁 router guard（DEV off 直接打 URL redirect）。
4. E2E 測試（compliance-manager-test）。

7. Changelog 索引

• docs/changelog/2026-05-31-feat-evidence-classify-analysis-reports.md
• docs/changelog/2026-05-31-feat-evidence-classify-ground-truth-import.md
• docs/changelog/2026-05-31-feat-evidence-classify-dev-mode.md

8. 相關文件

• 設計：docs/features/FR-031-2605-evidence-classify-reports/design.md（§5 演算法 / §13 Reconciliation）
• API：docs/api/evidence-classification/api-spec.md §8–10
• 正解操作：docs/api/evidence-classification/ground-truth-operations.md
• 收尾 SUMMARY：docs/features/FR-031-2605-evidence-classify-reports/handoff/2026-05-31-SUMMARY.md