Guidant AI v1.1.0 Release Note

版號統一說明：本版起 BE 與 FE 版號對齊為 1.1.0。FE 早期已定版 1.0.0，BE 一直未正式做進版流程（停在 0.3.0）。本次發 v0.4.0 後發現對不齊，user 決議兩端統一進到 1.1.0（FE 從 1.0.0 → 1.1.0，BE 從 0.3.0 跳過 0.4 / 1.0 直接到 1.1.0），日後 BE / FE 一律 1:1 對齊。原 v0.4.0 tag 已撤回。

1. 概述

v1.1.0 累積 2 個月的功能開發，重心放在 SSP（System Security Plan）端到端能力：從 OSCAL 模板的匯入匯出、SSP 編輯整合進專案規劃頁、到受評範圍從 project 層遷移到 SSP 層 — 共完成 13 個主要 feature 區塊。同時補齊 AI Dashboard DDD 架構、Google Drive 整合、BPMN/Flow Engine 多輪審查、Audit Lifecycle archived 判定等橫向強化。

本版含 9 個 breaking change（多為內部 API contract 修正，FE 已同步更新），需配合 DB migration（Phase 2 + Phase 3 兩段 SQL）與 jedi-* 套件多筆進版。

2. 重點新功能

2.1 SSP 匯入匯出 Phase 2（A 匯入 + B 匯出）

完整 SSP Excel/DOCX/OSCAL JSON-YAML-XML 端到端流程：

• A 匯入：
  • Excel template 下載（framework-version-scoped，含 superset endpoint）
  • 9-sheet parser（party / device / information-system / external-leveraged / control-implementation / system-characteristic 等）+ version check + 13 個 validator
  • Party matcher（user / org_unit fuzzy match + 後台 enrich）
  • Write pipeline（A4 confirm + row-level overrides / delete + idempotent responsible-party）
  • Preview 頁 row edit + removed rows 支援
• B 匯出：
  • DOCX 匯出（v2 template rebuild、CMMC SSP 正式格式、封面 + 動態 loop）
  • OSCAL JSON / YAML / XML 三格式匯出（SSP version route）
  • LibreOffice binary 自動偵測（含 macOS soffice fallback）
  • Unicode 中文檔名修正

Reference: docs/features/FR-011.2-2605-ssp-import-export-phase2/、docs/changelog/2026-05-19~2026-05-22-*ssp*

2.2 SSP Edit-in-Project（Phase C / D + Track A/B/C）

把 SSP 編輯能力整進專案規劃頁，並完成受評範圍的 schema 大遷移：

• C1 — OSCAL SSP 角色 master data 化：9 個 OSCAL 標準角色（system-owner / authorizing-official / asset-administrator ...）seed 進 system_menus + oscal_roles
• C2 — SSP-scoped endpoints：19 個 SSP-scoped API（含 party / device / information-system / leveraged / document-pool / system-characteristic 全套 CRUD）
• C3 — 受評範圍遷移到 SSP 層（兩階段）：
  • PR1：response derived from SSP + 寫操作 endpoint 退 410 Gone
  • PR2：DROP compliance.project_device_mapping + project_information_systems，拆 device / pis Python stack
• C4 — 專案 CRUD 拿掉 audit_systems / devices 欄位
• C5 + D — 專案規劃頁加 SSP tab：Accordion → TabView，6 sub-tabs（受評標的 + 4 個 panel + intro）
• C6 — 移除專案設定 UI 的「受評範圍」段
• C7 — 06_外部利用服務 sheet 恢復 + provider / category 結構化欄位
• C8 — _ROLE_LABEL_MAP 清理 + role id 修正
• Track A — MF / SSP 結構對齊（受評標的 + 外部利用服務 endpoint + 啟動專案 clone SC）
• Track B — SSP Excel system_characteristic 端到端 + leveraged 結構化欄位（template v2.4.0）
• Track C — 專案 SSP tab Excel 匯出匯入 round-trip
• Project Settings 整合 — 3 panel 整進專案規劃頁（5 flat tab）

Reference: docs/features/FR-011.3-2605-ssp-edit-in-project/

2.3 SSP Update Diff

支援已 ship 的 SSP 重新匯入 .docx 時，先以 side-by-side diff 預覽（current vs parsed）、smart default 推薦、user 確認後才寫入。完整 5-agent code review。

Reference: docs/features/FR-025-2605-ssp-update-diff/、docs/review/2026-05-07-ssp-update-diff-review.md

2.4 合規框架 PDF 匯入 v2.x

PDF 框架匯入支援編輯模式 + baseline scope guard + 即時重新上傳覆蓋 + iframe 找不到檔案 fallback 顯示。Phase A.1 SSP doc parser migration 完成（branch feat/ssp-doc-parser）。jedi-oscal 0.0.16 配套發版。

2.5 Google Drive 整合 v1~v3

• v1：OAuth + folder init
• v2：folder init / rename 自動同步
• v3：跨資料夾 perf 優化 + scope reduce

Reference: docs/changelog/2026-04-23~2026-05-09-*google-drive*

2.6 AI Dashboard DDD 重構

• 架構分層：Domain / Infra / App 三層
• 端點清理：移除棄用 endpoints
• Route 層 Marshmallow 重構
• DTO / Gateway rename

2.7 BPMN / Flow Engine 多輪審查 + 強化

• Stage 拓樸規則放寬
• Gateway auto-name illegal_invocation 修正
• Gateway condition quote / raw input 處理
• Publish violations 不再丟失
• Validator 改用 names 而非 ids
• 多輪 review stage 支援
• Banner button label 動態化 + 進度按 user task

Reference: docs/changelog/2026-05-15-*bpmn*, *flow*

2.8 Spec 3 — Flow Template Required

建專案 / launch new round 強制指定 flow_template_uid，拔掉 Spec 2 的過渡 hardcode；補 launch_new_round 漏綁 main workflow snapshot 的問題（影響第二輪以後 Banner 推進按鈕）。

2.9 Task Survey Phase 2 / 3

• Phase 2：多人協作一致性 — 單題 patch + on_join 改 DB
• Phase 3：暫存 / 提交改 patches-based checkpoint endpoint + socket broadcast shape 對齊

2.10 系統設計文件全面補齊

8+ 模組（auth / flow / survey / grc / oscal / module-frame / participant / project / system-tool）SDD + API reference DOCX + Swagger 補洞 + 架構圖。

Reference: docs/system-design/

2.11 GitLab CI Claude code review

CI pipeline 整合 Claude code review，PR 自動分析。

2.12 Audit Lifecycle 強化

• Auditor Dashboard 排除軟刪除 / 改用 archived 判定
• Job Import Confirm 保留審查人員
• Reviewer role 開放 launch audit
• Job 不退回已稽核 AP
• Spec3 follow-up（completion rate unit test / launch audit dead code / sync project status helper）

2.13 RLS 與 super admin 機制

tenant_id 改走 super-admin 判定（取代既有 is_super_admin flag 的部分情境）。

3. 重要修補（節選）

• task_survey 多人協作答案重複寫入根因修正（Phase 1 + Phase 2）
• confirm-audit finding repo DI 註冊錯誤 + 缺失紀錄前置驗證
• SSP shell metadata_id NOT NULL + 殘留 fw_version.catalog_id 修補
• _resolve_catalog_id 走 fw_version.catalog.id（修 superset 流 reconciler 全 skip）
• ssp_excel confirm 對 legacy blocking code (INVALID_ROLE) 向後相容
• ssp_excel person role 改 non-blocking warning（相容 OSCAL 角色）
• DI: module_frame_container ssp_domain_service 補 document_repo 注入
• ssp_system_characteristic empty fallback + PUT auto-create
• 啟動專案 clone leveraged 補 category + provider 欄位
• file-preview 加 odt / ods / odp / rtf 到 PDF 轉換 whitelist
• ssp-excel-confirm ControlWriteStrategy 改用 control_identifier upsert key
• ssp-scoped-excel permission_checker 包 session_scope

完整修補清單見 docs/changelog/2026-04-*-fix-*.md 與 docs/changelog/2026-05-*-fix-*.md。

4. Breaking Changes

5. DB Migration 需求

部署前必須依序 apply 兩段 consolidated SQL，帳號 cmmgr（cm_app 受 RLS 擋）：

# Phase 2（涵蓋 A0 / A0.1 / device_id backfill / A2 parse_jobs）
psql -h <DB_HOST> -p <DB_PORT> -U cmmgr -d <DB_NAME> \
    -f scripts/sql/2026-05-22-ssp-import-export-phase2-upgrade.sql

# Phase 3（涵蓋 C1 seed roles / C8 fix role_id / C3 PR1 backfill / C7 provider+category / C3 PR2 DROP 舊表）
psql -h <DB_HOST> -p <DB_PORT> -U cmmgr -d <DB_NAME> \
    -f scripts/sql/2026-05-23-phase3-consolidated.sql

驗證查詢與順序考量見 docs/features/FR-011.3-2605-ssp-edit-in-project/handoff/2026-05-23-phase2-phase3-sql-apply.md。

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

6. 相依套件版本

部署環境執行 poetry update 即可同步 poetry.lock 內 pin 版本。

7. 部署順序

1. 跑 SQL：先 phase2 consolidated，後 phase3 consolidated（帳號 cmmgr）
2. 更新主專案 code：pull main（含 pyproject.toml 已 pin v1.1.0 + jedi-* 新版）
3. 更新相依套件：poetry update（如部署環境用 lock，已固定到對應版本）
4. 重啟 BE：

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

   （nohup 留 orphan PID 是已知問題，必須 kill -9 強制）
5. Smoke 驗證：
   • GET /ssp/<uid>/system-characteristic 回 200 + payload
   • GET /ssp/<uid>/leveraged items 含 provider / category 欄位
   • GET /ssp/<uid>/excel-template?mode=blank 下載 xlsx
   • GET /module-frame/<uid>/system-characteristic 回 200
   • 啟動新專案後 SSP 的 SC + leveraged 有從 template clone
   • 專案規劃頁 SSP tab 6 sub-tabs 全顯示
   • 「我的待辦任務」批次完成 checkbox 正常（一般任務 + 問卷任務）

8. 已知 Follow-up

• 既有專案 leveraged row 缺 provider / category：因前期 clone 流程沒帶；新 round / 新專案會自然修復。要立刻補可在 SSP UI edit dialog 手動填。
• MF SC / leveraged endpoint BE unit test：A1/A2 是 thin delegate，test 留下一輪補。
• 預覽頁 confirm 後 ?section=ssp deep-link 沒實作：跳回 project-planning-ap route 但 SSP tab 切換需 user 手動點。
• Task assignee bug 剩餘修復：jedi-auth _in_* 根因修復 / 2,370 筆髒資料清理 / poam_service.py:152 同模式檢修。
• RLS session_scope else 段收緊：目前無 context 暫開 is_super_admin='t'，待盤點所有觸發情境後改 'f'。

9. 完整 Changelog 索引

按時間倒序：

• docs/changelog/2026-05-23-*.md（Track B/A/C ship + C3 PR2 + bug fix collection）
• docs/changelog/2026-05-22-*.md（Phase C1/C2/C7/C8 + DOCX export + Excel leveraged restore）
• docs/changelog/2026-05-21-*.md（Phase 2 A5 + 多項 fix）
• docs/changelog/2026-05-20-*.md（Phase 2 A4 write pipeline + party matcher）
• docs/changelog/2026-05-19-*.md（MF/SSP import template by framework-version + UX polish）
• docs/changelog/2026-05-18-*.md（SSP system_impl extension + conversation history archive rules）
• docs/changelog/2026-05-1[3-5]-*.md（BPMN / Flow Engine 強化 + Spec 3）
• docs/changelog/2026-05-0[6-9]-*.md（SSP Update Diff + attachment_count + Google Drive scope reduce）
• docs/changelog/2026-04-*-*.md（AI Dashboard 重構 + Google Drive 整合 + 系統設計文件 + Audit Lifecycle）

10. 相關文件索引