Guidant AI v1.5.0 Release Note

1. 概述

v1.5.0 是 FR-038 OSCAL 核心 v1→v2 架構重設計整個大弧的發版，外加前置的 FR-036 樣板 SSP 整併：

• OSCAL v2 引擎（jedi-oscal-v2 2.0.0）：把「只套用 OSCAL 概念、大量自定義欄位、用 AP 兼當稽核輪次」的舊架構，重寫成正式 OSCAL v1.2.2 物件模型落地、三層 clone/snapshot 邊界清楚的關聯式 schema。
• 稽核輪次模型：產品模型從「專案 → AP（單一評估計畫）」改成「專案 → 稽核輪次（round）」，每輪有自己 round-scoped 的 SSP 快照 / AP / AR / POA&M（compliance.project_audit_rounds first-class）。
• 主專案 BE 地基翻轉：從舊 jedi_oscal(v1) 切到 jedi_oscal_v2(v2)；因兩者 ORM 撞在 jedi_common 同一 declarative Base、無法共存，採 big-bang 一次性全切。
• v2 業務面重建：規劃頁 / 總覽 / 覆核 / 任務 ↔︎ BPMN 雙向同步 / SSP 差異更新匯入 / 程序書啟動專案複製等，整套接回 v2。
• FR-036 樣板 SSP 整併：資源庫範本內容從獨立的 module_frame_*_defaults（8 表）整併進「樣板 SSP」（module_frames.template_ssp_id → oscal.ssps WHERE is_template=true），消除雙 schema drift。
• 2 個 jedi- 套件升版並推 Nexus*：jedi-oscal-v2 2.0.0（新）、jedi-oscal 0.0.23（FR-036 改動訂版留存）。

2. 重點新功能

2.1 OSCAL v2 引擎 — jedi-oscal-v2 2.0.0（FR-038 Wave 1）

• 從零建成的 OSCAL v1.2.2 關聯式落地套件：七大 root 物件、完整 Catalog 階層（catalog → group → control → part）、Profile imports 關聯化、完整 SSP 子樹（system-characteristics / system-implementation / control-implementation）。
• 三層 clone/snapshot 架構：公版（資源庫樣板）→ 專案 living SSP → round frozen SSP。
• CMMC 2.0 + ISO/IEC 27001:2022 adapter；OSCAL JSON ↔︎ 關聯式雙向轉換（import_ssp / export_oscal）。

2.2 稽核輪次（round）模型（FR-038 Wave 2B）

• compliance.project_audit_rounds（7 態 + parent_round_id），每輪綁自己的 SSP 快照 / AP / AR / POA&M。
• 專案列表狀態改顯示「最新一輪」；稽核計畫改輪次總數。

2.3 規劃頁 / 總覽 v2 遷移（round-first）

• 入口 round-first（apUid = roundUid ?? apUid），一律解析 audit-rounds/list。
• 控制項樹改吃 GET /ssp/<sspUid>/control-tree（群組→控制項→AO + 現況 + 收證據 job 一次回全）。
• 可編輯判定改看 round.status==='planning'；新增 project-planning-round / project-auditor-overview-round 路由。

2.4 AO 任務 ↔︎ BPMN userTask 雙向同步（補回既有功能）

• grc_job_repo.create_job / delete_job v2 重建，idempotent on (workflow_execution, template_job_id)，防 BPMN 編輯器重複建任務。
• 任務 name/描述/指南/類型以 cloned BPMN userTask 為來源；syncTaskToTemplate 改「屬性不存在就建立」。

2.5 SSP 差異更新匯入復原（接回 v2）

• 上傳 docx/excel → 逐項差異比對 → 接受/保留決策 → 人員三層自動比對 → 未匹配段落手動指派 → 寫入更新，整套 FR-011.2 體驗接回 jedi_oscal_v2。
• 架構決策 W2：decision 在「parsed OSCAL dict ↔︎ snapshot OSCAL dict」層 merge 成單一最終 dict，呼 import_ssp(mode='update') 一次寫入（不復活 v1 write strategy）。

2.6 程序書啟動專案複製

• project_start._clone_reference_documents：程序書池（ssp_reference_documents）+ 控制項/AO 連結（ssp_reference_document_mappings）公版→專案複製（deep_clone_ssp 只 clone 12 張標準子表，程序書是 GRC 擴充表需另補）。

2.7 FR-036 樣板 SSP 整併

• 範本內容整併進樣板 SSP，退役 8 張 module_frame_*_defaults；所有 live 讀寫路徑改源樣板 SSP。

3. 重要修補（FR-038 弧內）

• AO/statement 識別碼統一 canonical _obj.N（修 AO 層現況/敘述帶不出、覆核閉環失效）。
• 控制項導航走 ProfileResolution（cloned catalog 全集 / profile 選擇性，讀取點 resolve）。
• docx 匯入 source type = project SSP；import-ssp by-component soft-ref 對齊 uuid（修敘述被丟）。
• 專案 SSP 匯入 manager 權限檢查移到 app service 層。
• 檔案預覽圖片 mimetype 修正。

4. Breaking Changes

• OSCAL schema 整個重建（v1→v2，不相容）：舊 oscal.* v1 表被 drop，重建為 v2 的 50+ 表。
• jedi_oscal(v1) 與 jedi_oscal_v2(v2) 不可共存：兩者 ORM 撞在 jedi_common 同一 declarative Base 的 MetaData → 主專案 big-bang 一次切到 v2，無 booting 中間態。
• 專案模型「專案→AP」改「專案→稽核輪次」：AP-scoped 流程改 round-scoped。
• 新依賴 jedi-oscal-v2==2.0.0；jedi-oscal 留存於 0.0.23（主專案仍有 30+ 頂層 v1 import，待後續整理）。

5. DB Migration（⚠️ 破壞性 v1→v2 cutover）

因 v1→v2 是「drop oscal 重建」式重設計，歷史 migration 不可逐檔線性 replay（多個歷史檔指向最終 v2 不存在的中途態）。已產出 cutover 工具：

• scripts/sql/2026-06-18-stg-v2-cutover.sh —— 清可丟業務資料 + drop 重建 oscal v2 + 套 FR-038 增量 + 補記 schema_migrations，最後對 DEV column-dump diff 驗零差異。
• scripts/sql/2026-06-18-stg-clear-orphan-project-task-data.sql —— 清軟刪除舊專案遺留的孤兒任務/job/workflow 資料。

涵蓋的 migration（自 1.4.0 後 25 個，依套用順序，已 stamp 在 cutover 腳本內）：oscal v2 base（oscal-catalog-and-roots-schema-v2.sql）+ delta（oscal-v2-deltas.sql）、project_audit_rounds、living-ssp 欄、AO statement canonical、framework/parse-jobs、round flow/stage seed、FR-036 template-ssp 欄 + drop defaults 等。

環境狀態：DEV + STG 已套（STG 2026-06-18 cutover，schema 對 DEV 零差異）；POC / PROD 待辦（同為破壞性 cutover，需 app 同版）。

6. 相依套件版本（本版升版）

其餘 jedi-* 維持 v1.4.0 的 pin（無異動）。

7. 部署順序

1. DB：在目標環境跑 v2 cutover（2026-06-18-stg-v2-cutover.sh 改連線 → 該環境）；確認對 DEV column diff 零差異。
2. app：上 feature/oscal-refactor build（含 jedi-oscal-v2==2.0.0 pin）並重啟。
3. v2 內容：cutover 後 frameworks / catalogs / module_frames 為空，透過 app 重匯框架 + 重建 module frame。
4. ⚠️ app 與 DB 須同版；舊 app 配 v2 schema 會炸。

8. 已知 follow-up

• AP-mode 死碼清理（FR-038 收尾 Part 1/2/3）：FE ap-mode 導航/元件移除 + BE 刪已停用 v1 路由/repo + task-setup 移除 —— 排另一 branch 配 code review 做。見 docs/features/FR-038-2606-oscal-redesign/handoff/2026-06-18-ap-mode-removal-handoff.md。
• v1→v2 import 整理：主專案 30+ 個頂層 jedi_oscal(v1) import（catalog assessment / party context / write strategy / AP·AR·profile route 等）待遷移到 v2 後才能移除 v1 依賴。
• 其他 review 未做項：R4 框架 Excel/YAML 匯入、M6 ai_dashboard OscalFramework resolver、M7 frameworks.main_version 雙真相、L1 dead write-strategy、L2 重複 error code、L4 stage precondition、ssp-import-template/control-defaults 填值完整 v2。見 docs/review/2026-06-18-fr038-api-inventory-dead-and-broken.md。
• POC / PROD cutover 未執行。

9. 完整 changelog 索引（自 1.4.0 後）

• 2026-06-10 feat-fr036-phase2-template-ssp-merge
• 2026-06-10 tweak-ssp-table-rename
• 2026-06-14 feat-fr038-wave1-jedi-oscal-v2-package
• 2026-06-14 tweak-fr038-wave2a-oscal-v2-foundation-flip
• 2026-06-16 feat-fr038-ssp-import-diff-update-restore
• 2026-06-16 fix-fr038-docx-import-source-type-project-ssp
• 2026-06-16 fix-fr038-import-ssp-by-component-comp-map-uuid
• 2026-06-16 fix-fr038-project-ssp-import-manager-gate-in-app-service
• 2026-06-17 feat-fr038-clone-reference-docs-on-project-start
• 2026-06-17 feat-fr038-planning-view-v2-migration
• 2026-06-17 feat-fr038-task-bpmn-bidirectional-sync
• 2026-06-17 fix-file-preview-image-mimetype
• 2026-06-17 fix-fr038-ao-statement-key-canonical
• 2026-06-17 fix-fr038-control-navigation-profile-scope

註：FR-038 2B 後段（dashboard 重建 / API 死碼盤點 / docx AO key 閉環 / 退役 v1 路由註解）部分仍以 commit message 詳載（a23f614e / 4880a0a0 / f7a9f752 / 2ed83f49 / d4a0f0bc），changelog 待收尾批次補。

10. 相關文件索引

• docs/features/FR-038-2606-oscal-redesign/（requirement-analysis / design / implementation-plan / handoff）
• docs/features/FR-037-2606-oscal-schema-gap-audit/（v2 base schema：oscal-catalog-and-roots-schema-v2.sql）
• docs/features/FR-036-*（樣板 SSP 整併）
• docs/review/2026-06-18-fr038-api-inventory-dead-and-broken.md（死碼/壞掉 API 盤點）
• docs/analysis/2026-06-18-import-export-v2-coverage-audit.md