Guidant AI v1.2.1 Release Note

1. 概述

v1.2.1 是 v1.2.0 之後的小版,主軸是把 AI 證據自動分類(CMMC L1 / NIST SP 800-171A 範圍)從 POC 推進到「dev demo-ready」狀態。

仍屬實驗階段:

• 沒有 DB 化(JobRegistry / state 都還靠 in-memory + Drive JSON)
• 僅支援 framework cmmc-l1
• 觸發 / 審閱 / 預覽全鏈路打通,適合內部 demo 與技術驗證,不建議直接給客戶用

另含一筆 v1.2.0 漏掉的 framework version delete FK cascade 修補。

2. 重點功能

2.1 AI Evidence Classification 從 POC 推進到 dev demo-ready

為什麼:CMMC L1 框架共 6 domain / 17 control / 59 評估項目,客戶端要手動把幾百份證據檔對照入位非常耗時。本期實作端到端 AI 自動分類:檔案放 Drive 一個資料夾 → 觸發後 BE 跑 docker container 用 Claude Sonnet 4.6 分類 → 結果寫回 Drive(自動分類_YYYY-MM-DD_HH-MM/ 三層分類資料夾)→ 前端審閱頁可逐檔調整 + 預覽 + 儲存。

端到端涵蓋:

• 觸發:專案總覽頁 trigger button + Dialog 顯示歷史 / 進度;trigger 後可直接關掉 Dialog,完成時 toast 通知
• Container:自包含 docker(cmmc-classifier:latest),內含 jedi_helpers fernet / OAuth 解密;sonnet 4.6 + prompt caching,~10 分鐘 134 檔
• 後置 Drive ops:BE worker thread 收尾,建 run folder + 三層分類資料夾 + copy 檔案(~17 分鐘 270+ copies)+ 上傳 _state.json / _report-original.json
• 審閱頁:檔案清單 / detail panel / AI 推薦候選卡 / 已配對卡 / AOPicker(可加可移除,顯示 AI 評分 pill)/ filter slider / 儲存變更
• 檔案預覽 Dialog:點 👁 圖示開啟,BE 經 OAuth proxy 從 Drive 抓檔。Office 格式(docx/doc/odt/xlsx/pptx etc.)on-the-fly 走 LibreOffice 轉 PDF(沿用既有 SspLibreOfficeConverter),browser 內嵌渲染
• 歷史復原:BE 重啟後 in-memory JobRegistry 雖然清空,trigger Dialog「歷史執行」會自動掃 Drive 重建紀錄(filter 自動分類_* subfolder),user 仍能進舊的審閱頁

為什麼不算大版:

• 框架硬綁 cmmc-l1(catalog 來自 repo 內 JSON)
• 沒 DB,無 audit log,無並發鎖
• 無 cross-tenant 支援,單 user / 單 tenant 試用

正式版要拉到 v2.x 才會做。

3. 重要修補

3.1 framework version delete FK cascade(v1.2.0 漏修)

刪除合規框架版本時 child rows(framework_control_groups / framework_controls 等)沒設 ON DELETE CASCADE,DELETE 撞 FK 失敗。本期補 migration 加 cascade。

詳見 docs/changelog/2026-05-27-fix-framework-version-delete-fk-cascade.md。

3.2 evidence-classify worker thread session_scope + tenant_id 來源

Trigger 後 worker thread 在 BE process 內背景跑(threading.Thread),需要查 OAuth token / drive_folder_mappings。兩個獨立 bug 連環炸:

1. ProjectEntity 沒暴露 tenant_id → 改從 JWT user context 取
2. ContextVar(user_context) + session_context 都 thread-local,新 thread 起來時是空的 → trigger 時 capture user_context 傳進 thread,worker 開頭重建,Drive 收尾段包 session_scope(刻意不包整個 worker 避免 ~10 分鐘長 session)

詳見 docs/analysis/2026-05-28-worker-thread-session-scope.md(含未來反悔條件)。

3.3 _resolve_tenant_for_run_folder 加 user.tenant_id fallback

BE 重啟後 JobRegistry 清空 → get_state / put_state / get_file_preview 三個 endpoint 都因為找不到對應 tenant 而 404。改成 registry 未命中 fallback 到當前 user 的 tenant(JWT 已驗證,RLS 已保證隔離,安全可接受)。

3.4 verify-and-repair-folders user.user_id typo(2026-05-28 commit 91c224e3)

api/cloud_integration/routes/google_drive_sync_route.py:148 寫成 user.user_id,但 UserContextDTO 屬性是 user.id。觸發 verify-and-repair 端點時 500 AttributeError。

3.5 Run folder 命名時區 + 歷史 dedup(2026-05-28 commits 543b2e1d / b7fa0e9f)

• 原 datetime.now(timezone.utc) → 改 datetime.now(ZoneInfo("Asia/Taipei")),server 在 UTC 也能輸出台北時間
• _finalize_drive_output 建好 run folder 後立刻 JobRegistry.update(run_folder_id=...),避免 Drive scan recovery 在 copy 期間重複出現一筆「已完成」entry

3'. 2026-05-29 後續微調(本 release 區間最後一天)

3'.1 minConf 範圍 0.5 → 0(FE commit c6e9de1)

ClassificationFilterBar slider 最小值改 0,點「未分類審閱」toggle 進入 inbox 自動把 minConf 拉到 0(離開時還原 0.80)。原本未分類檔多半 AI 信心低 < 0.5 被 filter 擋掉,user 進 inbox 看不到目標檔的矛盾。

3'.2 drive_ready gate 暫時拿掉(FE commit c6e9de1,待加回)

STG demo 錄影期間,既有專案 EVIDENCES mapping backfill 還沒做完 → drive_ready=false → 按鈕不顯示無法 demo。先把 ProjectAuditorOverview.vue v-if 拿掉 && ecJobs.driveReady.value,等 STG 部署完整後加回。Spec 跟 v1.2.1 §8 都有標 follow-up。

3'.3 MF template edit jump-to-control tab 切換(FE commit 7505603)

跨主題 fix:ModuleFrameTemplateEditView.vue:jumpToControlByUid 強制 activeTab.value = 1,確保跳到 control 時 tree 已 mount;jumpToAo setTimeout 100→200ms 讓 tab + tree + lazy AO render 完成才 flash。

4. Breaking Changes

無。

5. DB Migration

無。evidence_classification 整個模組 v0 階段沒新增 table(state 存 Drive JSON,JobRegistry 存 BE 記憶體)。

6. 相依套件版本

外部新增需求:

• LibreOffice(host 機已有) — docx → pdf 轉檔,沿用 SSP 匯出既有依賴
• Docker(host 機已有) — 跑 cmmc-classifier:latest,自包含

7. 部署順序

1. 取本版 git pull + git checkout v1.2.1(或 fearure/ai-evidence-classify 對應 commit)
2. poetry update(本期沒動套件,跑一次無害)
3. 重啟 BE:

   lsof -ti :8000 | xargs kill -9 && python main_socketio.py

4. (僅 dev / staging 啟用 evidence-classify) build classifier image:

   cd scripts/evidence/classify/docker
   docker build -t cmmc-classifier:latest .

5. Smoke 驗證:
   • 登入 → 進專案總覽
   • 點「自動分類證據」開 Dialog → 看「歷史執行」是否從 Drive 撈回舊紀錄
   • 點任一歷史紀錄「查看分類結果」進審閱頁 → 檔案清單顯示
   • 點檔案 👁 圖示 → 預覽 Dialog 開啟,docx 自動轉 PDF 內嵌渲染
   • 編輯 placement / 點「儲存變更」→ 看 toast + Drive 上對應資料夾有 copy / trash

8. 已知 Follow-up(本版未做,排程到 v1.3 / v2.x)

8.1 evidence-classify v0 → v1 DB 化(高優先)

• 問題:JobRegistry 是 in-memory dict,BE 重啟後本期觸發的 job 紀錄消失(歷史紀錄靠 Drive scan 復原是 workaround,但跑中的 job 無法跨重啟)
• 規劃:新增 3 張表(evidence_classification_jobs / evidence_classification_runs / evidence_classification_audit),把 trigger / status / run folder reverse-lookup 全搬 DB
• 效益:支援多 user 並發、跨重啟、auditor read-only 權限、cross-run 比對

8.2 cross-tenant super admin 支援

• 問題:目前 service 從 user.tenant_id 取 tenant,假設 user 與 project 必同 tenant。Super admin 跨 tenant 操作時這假設不成立
• 規劃:見 docs/analysis/2026-05-28-worker-thread-session-scope.md 第 Bug A 段 — 5 步必須一起做(jedi-project 暴露 tenant_id + service 改用 project.tenant_id + RLS 鬆綁 + 權限檢查 cross-tenant aware)

8.3 evidence-classify experimental → production 化

• Framework catalog 從 repo JSON 改 DB(支援多 framework / 動態定義)
• 加並發鎖(同 run folder 兩 user 同時 PUT 不會 last-write-wins)
• DB-backed audit log(目前唯一 audit 來源是 Drive _state.json revisions)
• LibreOffice docx → pdf 加快取(同檔案多次預覽不重複轉)

8.4 預覽 UX 細節

• docx → pdf 轉換 1-3 秒,目前 loading 只有 spinner + 「載入中...」,可加更明顯的「正在轉換 Word 文件...」訊息
• 大檔(> 50MB)目前直接 raise,可加 partial download / 串流預覽

8.5 AOPicker 大型 framework 效能

• CMMC L1 有 59 評估項目,單頁 scroll 沒問題
• 但 ISO 27001 / NIST SP 800-53 有 200+ 控制項,scroll 會卡。要做虛擬列表

8.6 BE / FE 版號對齊

• BE 進到 v1.2.1,FE 也要對齊到 v1.2.1
• 建議切到 FE repo 開新 session 處理(避免跨 repo 改檔)

8.7 drive_ready gate 加回(最高優先)

• 2026-05-29 commit c6e9de1 為 STG demo 暫時拿掉 ProjectAuditorOverview.vue v-if 的 && ecJobs.driveReady.value
• STG 部署完整 + 既有 project 重跑 init folders 補 EVIDENCES mapping 後立刻加回
• 否則未連 Drive 的專案也會顯示按鈕,點下去才 toast 紅字,UX 不好

9. 完整 Changelog 索引

BE(compliance-manager-be/docs/changelog/):

• 2026-05-27-fix-framework-version-delete-fk-cascade.md
• 2026-05-28-fix-evidence-classify-worker-session.md
• 2026-05-28-feat-evidence-preview-history-recovery.md
• 2026-05-28-feat-evidence-classify-evidences-scope.md
• 2026-05-28-fix-verify-repair-folders-user-attr.md
• 2026-05-28-fix-evidence-classify-history-dedup-localtime.md
• 2026-05-28-fix-evidence-classify-run-folder-tz.md

FE(compliance-manager-fe/docs/changelog/):

• 2026-05-28-tweak-evidence-classify-ux-polish.md
• 2026-05-28-feat-evidence-preview-history-recovery.md
• 2026-05-28-feat-evidence-classify-drive-ready-gating.md
• 2026-05-29-tweak-evidence-classify-low-conf-filter.md
• 2026-05-29-tweak-mf-template-jump-to-control-tab-switch.md

10. 相關文件索引