手冊首頁 ／ Release Notes ／ Guidant AI v1.8.0 Release Note
Guidant AI v1.8.0 Release Note
| 項目 | 內容 |
|---|---|
| 版本 | 1.8.0（功能版號；主軸＝顧問交付文件匯入 — AP docx / AR xlsx 兩條三段式匯入管線） |
| 發布日期 | 2026-07-04 |
| 上一版本 | 1.7.2（2026-06-30） |
| 涵蓋區間 | 2026-07-02 ~ 2026-07-04 |
| 規模 | 2 個新功能（FR-043 稽核計畫 docx 匯入 / FR-044 稽核紀錄 xlsx 匯入）+ FR-045 CMMC v2.13 PDF parser 相容 + 自動證據分類 container RLS 修正，跨 BE + FE + jedi-oscal-v2 |
| 適用部署 | dev / staging / poc（3 支 migration 已全套）；prod 待 |
| 部署性質 | 非破壞性 schema（僅新增 2 張 parse job 表 + 1 欄），含新匯入端點與 UI。含 3 支 DB migration + jedi-oscal-v2 2.2.0 pin。BE 需重啟生效；自動分類 classifier docker image 需各主機 rebuild。 |
1. 概述
v1.8.0 主線是把顧問交付的稽核文件變成可匯入的資料，讓 PM / 稽核單位不必手動逐條輸入：
- FR-043 稽核計畫 docx 匯入：ap-authoring 頁上傳顧問交付的 Word 稽核報告，解析章節預填成行程資料，預覽 / 修改 / 確認後建進稽核計畫（AP）。
- FR-044 稽核紀錄 xlsx 匯入：稽核執行頁上傳逐條檢查紀錄 xlsx，解析成控制層判定 ＋ 逐 AO 觀察 ＋ 佐證連結，批次寫入本輪稽核結果（AR）；NOT MET 自動建風險、佐證分級配對。
- FR-045 CMMC v2.13 parser 相容：合規框架 PDF 匯入的 CMMC parser 支援 2024 官方 Assessment Guide v2.13（FAR 式編號），單一 adapter 同吃 2021 舊版 + 2024 新版四份 guide。
- 自動證據分類 container RLS 修正：分類 container 裸連線讀 Drive 整合被 06-28 RLS 收緊打壞，補設 super admin session 變數繞過。
版本定位 1.8.0（功能版號）：兩條全新匯入管線屬有意義的能力提升，依版號定義走功能版號 bump。
2. 重點新功能
2.1 FR-043 稽核計畫 docx 匯入（ap-authoring import）
- 三段式管線：
POST /ap/<ap_uid>/docx-imports/parse（上傳解析）→GET /ap-docx-import/<parse_uid>（預覽）→POST .../confirm（確認寫入）→DELETE（廢棄）。 - 零新增 AP schema 欄位：docx 章節（稽核單位 / 日期 / 範圍 / 方法）全對應現有 AP 欄位；依據 / 目的歸屬 SSP，預覽時作為參考資訊可勾附備註。
- 寫入不另開 write path：confirm 呼叫既有
AssessmentPlanAppService.set_tasks()+add_ap_party()，audit_planning 階段檢查 / Tab2/Tab3 回填 / activity 落地全部繼承。 - 權限 fail-closed（manager|auditor + audit_planning）；parser 走規則式 adapter registry，本期支援亞航 CMMC L1 格式，架構可擴充多版本。
2.2 FR-044 稽核紀錄 xlsx 匯入（ar-authoring import）
- 三段式管線 mirror
FR-043：
POST /ar/<round_uid>/xlsx-imports/parse→GET /ar-xlsx-import/<parse_uid>→POST .../confirm→DELETE。 - 核心四態判定
met / not_met / not_applicable / pending（承載跨框架）；observation 粒度 = 一 AO 一列；NOT MET 自動建風險（嚴重度預設「中」）；佐證分級配對（精確自動勾 / 模糊勾＋徽章 / 無配對人工補），不自動上傳建檔。 - 共用 import
基建：
app/grc/service/import_adapter/（自 FR-043 上收泛化的 registry），AP docx 與 AR xlsx 各一 adapter；template adapter × framework profile 兩軸拆開，可各自擴充。 - 重匯 = 最新覆蓋：parse_job
import_summary追蹤observation_uids，同輪重傳先清上一批匯入觀察再寫入，手動觀察不動。
2.3 FR-045 CMMC 2.0 v2.13 PDF parser 相容（jedi-oscal-v2）
- 單一 adapter 同時吃 2021 舊版 + 2024 v2.13 新版 L1/L2 四份 guide，四個 root cause 修法：雙格式編號 alternation + 全大寫 ID 正規化 / 字型分流解疊字 / 結構標題豁免 TOC 過濾 / 字級過濾去上標雜訊。
- 改動全在 jedi-oscal-v2
cmmc2_lv2_parser_adapter.py（單檔）+ 測試，主專案 BE 零程式碼改動。四檔 E2E 通過、2021 舊檔 baseline 逐條零差異、套件 62 tests passed。
3. 重要修補（FR-044 STG 上線後修）
| 主題 | 症狀 | 修法 |
|---|---|---|
| return_response 頂層 meta 陷阱 | preview 回 data: null，controls/observations
全消失 |
app service 摘要欄 meta 改名
report_meta，避開全域 helper 魔法分支（BE + FE） |
| 兩代 catalog control-id 共存 | v2.13 AG 式輪次交集為空 →
誤觸「框架不符」GRC_400095 |
identity-first candidate resolution：AG 原值優先，僅舊 NIST 式
catalog 才 fallback AG_TO_NIST |
| 佐證池跨控制汙染 | 存進不屬該控制的 evidence uid、稽核頁看不到 | 以 workflow_execution_control_mapping 對候選池二次
scope |
| 佐證預覽查無檔案 | 點佐證回查無檔案 | file_uid 存 upload_files 字串 uid（非數字
file_id） |
| 自動分類 container RLS | classifier exit 1
No Drive integration for tenant 102 |
container 裸連線查詢前 SET app.is_super_admin='t' |
4. Breaking Changes
無對外 API breaking change。新增端點與 UI，既有行為不變（手動累加觀察 / 既有 AP set_tasks 語意皆保留）。
5. DB Migration
| 順序 | 檔案 | 說明 |
|---|---|---|
| 1 | scripts/sql/2026-07-02-ap-docx-parse-jobs.sql |
新建 oscal.ap_docx_parse_jobs（FR-043 解析工作記錄，TTL
24h）+ RLS + GRANT cm_app |
| 2 | scripts/sql/2026-07-02-ap-docx-parse-jobs-add-org-unit-id.sql |
ap_docx_parse_jobs 補多租戶 org_unit_id
欄位（idempotent） |
| 3 | scripts/sql/2026-07-03-ar-xlsx-parse-jobs.sql |
新建 oscal.ar_xlsx_parse_jobs（FR-044 解析工作記錄，含
org_unit_id）+ RLS + GRANT cm_app |
- 非破壞性（僅新增表 / 欄，無 drop）。
- dev / stg / poc 已全套（poc 於 2026-07-04 套）；prod 待部署時程。
6. 相依套件版本
| 套件 | 版本 | 說明 |
|---|---|---|
| jedi-oscal-v2 | 2.2.0 | FR-044 not_applicable 第四態 + FR-045 CMMC v2.13 PDF
parser 相容（單 adapter 雙格式） |
其餘 jedi-* 維持 v1.7.2 既有 pin。
7. 部署順序
- DB migration（prod）：依 §5 表格順序 1→3 各跑（dev/stg/poc 已套）。
- BE：
poetry update jedi-oscal-v2（拉 2.2.0）後重啟（無 hot reload）。 - 自動分類 classifier docker
image：各主機各自
scripts/evidence/classify/docker/rebuild.sh（container_entrypoint RLS 修正才生效）。 - FE：build + 部署（版號對齊 1.8.0）。
- 驗證：ap-authoring 上傳 docx / ar-authoring 上傳 xlsx → 預覽 → 確認寫入；合規框架匯入 CMMC v2.13 PDF；自動證據分類可取得 tenant Drive token 跑完。
8. 已知 follow-up
- prod migration 未套：本版 3 支 migration 僅 dev/stg/poc 已套，prod 待部署時程。
- CMMC 匯入 Interview/Test 不進系統：parser 解析三桶但 BE 僅留 examine → guidance；要落地需獨立 FR。
- DEV
public.tenant_drive_integrationsRLS 關閉 = DEV/STG schema drift，待補開或記錄豁免。 - 盤點其他「裸 engine 讀 RLS 表」的 script / 排程 / agent，確認沒被 06-28 RLS 收緊打壞。
9. 完整 changelog 索引（v1.7.2 之後）
docs/changelog/2026-07-02-feat-fr043-ap-docx-import.mddocs/changelog/2026-07-04-feat-fr044-ar-xlsx-import.mddocs/changelog/2026-07-04-feat-fr044-reimport-latest-overwrite.mddocs/changelog/2026-07-04-fix-fr044-return-response-meta-trap.mddocs/changelog/2026-07-04-fix-fr044-evidence-pool-cross-control.mddocs/changelog/2026-07-04-fix-fr044-two-gen-catalog-identity-first.mddocs/changelog/2026-07-04-fix-fr045-cmmc-v213-parser-compat.mddocs/changelog/2026-07-04-fix-evidence-classify-container-rls.md
10. 相關文件索引
docs/features/FR-043-2607-ap-docx-import/（design / implementation-plan）docs/features/FR-044-2607-ar-xlsx-import/（design / implementation-plan）docs/analysis/2026-07-02-ap-docx-import-oscal-mapping.mddocs/analysis/2026-07-03-ar-import-verdict-mapping.mddocs/analysis/2026-07-04-fr044-stg-bugfix-decisions.mddocs/analysis/2026-07-04-cmmc-v213-parser-compat.md- Notion：FR-043 / FR-044 案；自動分類 container RLS
393346da-4cd0-81ae-8f59-dbddb86041b6