Guidant AI v1.2.0 Release Note

1. 概述

v1.2.0 完成兩條主線：

1. SSP OSCAL 結構對齊：把 ssp_system_implementation_items 單表拆成符合 OSCAL 規範的 3 個 entity（ssp_components / ssp_leveraged_authorizations / ssp_inventory_items），同步重構 import pipeline（Phase 1+2）、補 MF template defaults 4 張表（Phase 2），並強化 docx import anchor extractor 架構。

2. 側邊欄選單分組：39 個扁平選單項目重組為 7 個可展開分組，空分組自動隱藏，選單管理改由 DB 驅動。

本版含 1 個 breaking change（舊 ssp_system_implementation_items 表移除），需配合 2 份 DB migration SQL。

2. 重點新功能

2.1 SSP OSCAL Alignment Phase 1+2（BREAKING）

為什麼：OSCAL 規範要求 leveraged-authorization（法律層級 ATO 繼承）、component（元件層級）、inventory-item（實例層級）三層分開存放。原來全擠在 ssp_system_implementation_items 單表用 category enum 區分，無法 round-trip 出 OSCAL JSON。

Phase 1 — Foundation：

• DB 新增 3 張表（含 RLS）：oscal.ssp_components、oscal.ssp_leveraged_authorizations、oscal.ssp_inventory_items
• jedi-oscal 0.0.19 配套：3 個新 entity / service / repo
• 舊 ssp_system_implementation_items 資料遷移 → 新三表後 DROP
• 主專案 18 個 caller 全 refactor

Phase 2 — Import Pipeline 對接：

• 新增獨立 import_pipeline/ module（warnings / normalizer / bundle_restore / confirm_service）
• 3 個 v3 write strategy
• Docx adapter 加 adapt_to_bundle() 輸出 v3
• Docx app service 走新 pipeline

Reference: docs/features/FR-028-2605-ssp-oscal-alignment/、docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase1-phase2.md

2.2 MF Template Defaults Phase 2

補 4 張 compliance.module_frame_*_defaults 表（per-MF scoped），根治 template-edit 4 個 tab 讀寫路徑不同源、docx import 反覆 fallback create 累積 orphan SSP 的問題：

• module_frame_component_defaults
• module_frame_leveraged_defaults
• module_frame_inventory_defaults
• module_frame_system_characteristic_defaults

啟動 OSCAL 專案時，這 4 個 tab 的 default 值會從 MF template 正確 clone 到新 SSP。

Reference: docs/changelog/2026-05-26-feat-mf-template-defaults-phase2.md

2.3 Docx Import Anchor Extractor 架構

新 anchor-based extractor 架構取代舊 sequential parser，支援多段落錨點精準定位。主要改善合規框架 docx 的解析準確率。

Reference: docs/changelog/2026-05-24-feat-docx-import-anchor-extractors.md

2.4 SSP Import Diff Stepper — 4-Key TabView（Bug O）

SSP docx import 預覽頁支援 4 個獨立 key 的 TabView 展開，每個 key 的 current / parsed diff 獨立顯示，解決 batch confirm 後 UI 無法逐項確認的問題。

Reference: docs/changelog/2026-05-25-feat-bug-o-diff-stepper-4key-tabview.md

2.5 側邊欄選單分組（Menu Group）

• public.ui_routes 新增 7 個分組節點（專案與任務 / 合規與稽核 / 溝通與互動 / 租戶與組織 / 系統管理 / 系統設定 / AI 與分析）
• 2 個原本寫死在 FE 的項目（專案儀表板 / 待辦任務）搬入 DB
• jedi-auth 剪枝邏輯：無可見子節點的分組自動隱藏
• AppMenuItem.vue 加遞迴 sub-menu 渲染
• i18n：zh-tw / en / zh-cn 三語言 group key

Reference: docs/features/FR-029-2605-menu-group/、docs/changelog/2026-05-26-feat-menu-group-restructure.md

3. 重要修補

4. Breaking Changes

5. DB Migration 需求

部署前依序執行兩份 SQL，帳號 cmmgr：

# 1. SSP OSCAL alignment + MF defaults（schema 建表 + 資料遷移 + 舊表 DROP）
psql -h <DB_HOST> -p <DB_PORT> -U cmmgr -d <DB_NAME> \
    -f scripts/sql/2026-05-26-staging-deploy-consolidated.sql

# 2. Menu group 選單分組（純資料，不動 schema）
psql -h <DB_HOST> -p <DB_PORT> -U cmmgr -d <DB_NAME> \
    -f scripts/sql/2026-05-26-menu-group-restructure.sql

✅ Staging (guidant_ai_stg) 已於 2026-05-26 完成 apply。

注意事項：

• Script 1 STEP 3 使用 CREATE TEMPORARY TABLE ... ON COMMIT DROP，psql 非 interactive 模式下 temp table auto-commit 即 drop，INSERT 會 error。STG 已手動確認新三表資料正確（dev 資料 268 筆已遷移；STG 為測試資料，影響可接受）。若需確保資料遷移，改以 BEGIN; ... COMMIT; 包裹整個 STEP 3 再執行。
• Script 1 若 STG 存在 template_module_frame_id 重複資料（測試資料多次建立同 template 的 SSP），需先清理重複後 STEP 7 才能建 unique index。

6. 相依套件版本

7. 部署順序

1. 跑 SQL：先 consolidated，後 menu-group（帳號 cmmgr）
2. 更新主專案 code：pull main
3. 更新相依套件：poetry update
4. 重啟 BE：

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

5. Smoke 驗證：
   • 登入後側邊欄顯示 7 個分組
   • 點開「專案與任務」展開 5 個子項目
   • /project/projects 新增專案按鈕可見
   • SSP tab 受評標的 / 外部利用服務資料正常顯示
   • MF template-edit 系統元件 tab 寫入後同頁讀回

8. 已知 Follow-up

• STEP 3 temp table ON COMMIT DROP 問題：STG 已 workaround，正式環境部署前建議修正 SQL 加 BEGIN/COMMIT 包裹
• MF template defaults Phase 3（inventory items M2M ref）：本期未完成
• SSP Excel import Phase 3（parser 對齊 v3 pipeline）：本期 Phase 2 dispatch 已落地，parser 待下輪

9. 完整 Changelog 索引

• docs/changelog/2026-05-26-feat-menu-group-restructure.md
• docs/changelog/2026-05-26-feat-mf-template-defaults-phase2.md
• docs/changelog/2026-05-26-fix-appmenuitem-submenu-rendering.md
• docs/changelog/2026-05-26-fix-getuserpagepermissions-nested-menu.md
• docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase1-phase2.md
• docs/changelog/2026-05-25-feat-bug-o-diff-stepper-4key-tabview.md
• docs/changelog/2026-05-25-fix-bug-pqr-parties-form.md
• docs/changelog/2026-05-25-fix-h6-write-strategy-residual.md
• docs/changelog/2026-05-24-feat-docx-import-anchor-extractors.md

10. 相關文件索引