跳轉到

Guidant AI v1.14.0 Release Note

項目 內容
版本 1.14.0（功能版號；主軸＝License 控管全案上線 + 檢測基準內容管理）
發布日期 2026-08-10
上一版本 1.13.0（2026-08-01）
涵蓋區間 2026-08-01 ~ 2026-08-10
涵蓋需求 FR-062 License 控管機制全案（.1~.10，含簽發端地基／產品端驗照／狀態機／執法／開通／簽發後台／通知／角色矩陣 license 維度／手動停權獨立軸／產品後台向 LC 請照）＋ FR-060 檢測基準內容管理（拆表＋分類＋內容瀏覽）
規模 跨 BE + FE + License Center（獨立 repo）三方；BE 134 commits（含 FR-060 25 支 + FR-062 44 支 + 其他收尾/文件/雜項）、FE 對應 commits、LC repo 今日 8 支；DB migration 24 支（fr058 尾聲 2 支 + fr059 尾聲 2 支 + fr060 全 6 支 + fr062 全 7 支 + 其他 7 支）
適用部署 dev（已驗）；STG 已部署；POC 已部署（FR-062 於 2026-08-10 完成雙環境部署與請照實測；FR-060 已於 2026-08-07 完成三環境上版）
部署性質 含 24 支 DB migration（三環境 DEV/STG/POC 已全數套用，見 §5）。新增獨立系統 License Center（獨立 repo license_center，獨立 DB，需另行部署見 §8）。新增必要環境變數：License 簽發公鑰清單（見 §4）。相依套件僅 jedi-auth 由 0.1.33 → 0.1.34。

0. 發版前回歸 gate

本版未執行 site-regression 自動 Core gate；FR-062 全案於 STG／POC 雙環境部署後由決策者逐項請照實測驗收通過（詳見 §9 部署 handover），FR-060 已於 2026-08-07 完成三環境上版並結案。放行依據為決策者當面驗收，非自動化 gate。

1. 概述

v1.14.0 是產品正式上線銷售前的最後一塊拼圖：License 控管機制全案落地。核心信任模型是「公司自建簽發端（License Center，獨立 repo 獨立 DB，私鑰不出機）＋ 產品端只驗不簽」——簽章引擎、按模組授權、到期狀態機與通知、執法降級、序號開通與機器指紋綁定、簽發 Web 後台，一次到位並完成雙環境（STG／POC）部署與請照實測。

同版收官的還有 FR-060 檢測基準內容管理——把 v1.13.0 剛上線的「掃描設定檔庫」從「只有名字的不透明二進位檔」升級為「選之前先看得到內容」：控制項清單瀏覽、人工待判項標示、三軸分類、改名編輯，並修復拆表過程中發現的兩個靜默漏洞（停用 profile 仍可派工、通知信退化成 UUID）。

2. 重點新功能

2.1 FR-062 License 控管機制（全案十輪）

  • 簽發端地基（.1）：Ed25519 簽章引擎 + CLI + License Center 獨立 DB（plans / license_issuance）。照檔格式歷經三次演進，現行 v2.1 三段式含 send_email 旗標。
  • 產品端驗照（.2）：config.tenant_licenses 資料模型、root 後台授權管理頁、FE 授權狀態頁；照綁頂層租戶，整條讀照鏈過租戶樹 resolve。
  • 狀態機＋橫幅（.3）：每日排程 cron 推進 notify → grace → readonly，conditional UPDATE 冪等；FE 全域到期橫幅；root tenant 特判豁免。
  • 執法進場（.4）：common/authz 新增第六軸＋全域唯讀 gate＋選單/任務型態動態過濾；兩支環境開關（LICENSE_ENFORCEMENT_ENABLED / LICENSE_READONLY_GATE_ENABLED）可整體關閉；/license/ 前綴整段豁免防死鎖。
  • 開通（.5）：離線（機器碼 → 簽照 → 上傳）與線上（序號＋指紋一鍵換照）兩路；線上路徑 License Center 開放公開 API，BE 代打並完整驗章。
  • 簽發 Web 後台（.6）：Tabler UI（pin 版入 static/vendor，不依賴 CDN）——客戶總覽、簽發/換發表單、詳情頁、照檔下載、客戶授權時間線。
  • 通知＋既有租戶發照 SOP（.7）：notify/grace/readonly 三段到期信（收件人＝三旗標聯集＋root fallback）；既有租戶發照護欄腳本（DEV 演練用）。
  • 角色矩陣 license 維度（.8，驗收回饋追加）：ui-routes 附 is_licensed，FE 未授權能力點反灰空框並顯示原因，繞過 UI 直打 API 亦回 403；roles 寫入端守門；建租戶 seed 第三道扣除未授權模組。
  • 手動停權獨立欄位（.9，追加）：停權升為獨立欄位，cron 每日排程不再覆寫人為決策；migration 回填刻意不寫 suspend_reason（該欄直接顯示給客戶）。
  • 產品後台向 LC 請照（.10，追加）：SaaS 續約從「LC 下載 → 產品上傳」兩趟手動搬檔，改為產品後台帶 API token 直打 LC 內部簽發 API 一鍵完成；LC 新增 API token 白名單＋管理頁。

2.2 FR-060 檢測基準內容管理

  • 控制項內容瀏覽：管理頁點進去可看完整控制項清單（編號／標題／說明／嚴重度／是否人工待判），可搜尋可篩選；摘要區直接給總數／自動檢查數／人工待判數，選之前就知道覆蓋率（實測 TWGCB-01-014 Ubuntu 22.04 覆蓋率僅 15%）。
  • url 型基準內容抽取（CM-1072，延伸納入）：外部網址型基準一樣看得到內容，BE 代下載（含 SSRF 五道防護），拿到 bytes 後走與壓縮檔完全相同的解析路徑；掃描路徑本身不變，仍是 agent 直接吃 URL。
  • 三軸分類與改名：主檔拆表解決「name 是唯一索引一部分、改不動」的根因問題，新增標的類型／標的產品／基準體系三軸分類（存 DB 由 root 維護，非 FE 寫死），任務下拉依標的類型分組。
  • 兩個靜默漏洞修復：拆表過程中 is_active 守門一度靜默失效（已停用 profile 仍可派工）、通知信「掃描設定」欄位一度靜默退化成 profile:<uuid>——皆已修復並補迴歸測試。

3. 重要修補

  • FR-062.10 CM-1179：請照未指定 deployment_mode 時改帶本站台 DEPLOYMENT_MODE，避免 LC 用預設值猜測簽出錯誤照（POC 首發實際踩過此坑）。
  • FR-062.9 CM-1173：migration 回填手動停權欄位時刻意不寫 suspend_reason，避免帶入內部備註誤顯示給客戶。
  • CM-1150：選單剪掉 root-only 的 License 授權管理入口誤露出問題。
  • CM-1151：新增租戶排除平台層 capability，修 IntegrityError。
  • CM-1155：重複上傳同一張現行照改為冪等，不再插重複列。
  • CM-1156：license 改綁頂層租戶，整條讀照鏈過租戶樹 resolve。
  • CM-1157：跨租戶重複 license_id 一律拒絕，四條落地路徑一處收斂。
  • CM-1159：時鐘回撥判定加 24h 容差窗＋專屬 error code。
  • CM-1160：DOCX preselect-new 改 capability 判定＋租戶管理員角色自動掛 is_admin。
  • CM-1162：本地檔讀取端不再要求 STORAGE_CONFIG，寫入讀取兩端語意對齊。
  • CM-1165②：未開通照專屬 error code，不再誤導成「綁錯機器」。
  • FR-060：_load_profile() is_active 守門 None is False 判定漏洞修復（無聲授權漏洞）；_humanize_profile_param() 通知信退化成 UUID 修復。
  • FR-060：CM-1047 停用後無法以同名再建。

4. 環境變數

新增（License 控管必要）：

  • License 簽發公鑰清單寫死於 common/license/public_keys.py（三環境各自獨立 kid：DEV 2ce3bb59a6f5a2ce / STG 04b1e65f100c6c8f / POC f3b562a6d9755527），非 env var 形式，但新環境部署必須先進此檔並 commit 才 build image，順序顛倒會報「未知的 kid」。
  • LICENSE_ENFORCEMENT_ENABLED / LICENSE_READONLY_GATE_ENABLED（選配，預設 true）——執法總開關，可整體關閉。

License Center（獨立服務）必要環境變數：私鑰、passphrase、DB 連線——請查 LC repo .env 或部署文件，一律不寫入版控。

沿用既有：檢測工具憑證加密沿用 FR-056 起的 DETECTION_TOOL_ENCRYPTION_KEY；FR-060 無新增環境變數。

5. DB Migration（24 支，三環境已全數套用）

依日期序（DEV/STG/POC 皆已套用完畢）：

2026-08-01  fr058-20-sonarqube-scan-mode-label
2026-08-01  fr058-21-sonarqube-upload-scan-mode
2026-08-01  fr058-22-openscap-content-path-advanced
2026-08-01  fr059-1-detection-tool-profiles
2026-08-01  fr059-2-detection-profile-capability
2026-08-01  fr059-3-detection-profile-menu-route
2026-08-01  fr059-3-param-schema-options-source
2026-08-01  fr059-4-fix-detection-profile-menu-pid
2026-08-02  fr058-23-gcb-setup-guide-remove-demo-note
2026-08-02  fr058-24-sonarqube-setup-guide-remove-csharp-warning
2026-08-02  reverify-round-narrow-ap-reviewed-controls
2026-08-03  cm1047-dtp-tenant-index-partial
2026-08-03  fr060-1-detection-profile-split                    ⚠️ 662 行，拆表核心
2026-08-03  fr060-2-detection-profile-taxonomies
2026-08-03  fr060-3-param-schema-extraction-declaration
2026-08-04  fr060-1b-detection-profile-split-adaptive
2026-08-04  fr060-3-dpv-source-validators
2026-08-08  fr062-2-license-menu-route
2026-08-08  fr062-2-tenant-licenses
2026-08-09  fr062-tenant-license-events
2026-08-10  fr062-10-license-lc-events
2026-08-10  fr062-8-license-menu-restructure
2026-08-10  fr062-9-license-manual-suspend
2026-08-10  fr062-license-group-sort-last

⚠️ FR-060 拆表 migration（fr060-1）舊表未 DROP——原表 rename 為 detection_tool_profiles_deprecated_20260803 觀察期保留，另案處理。

License Center 端有自己獨立的 migration（license_center/scripts/sql/ 001/002），不進本專案 schema_migrations，走 LC repo 自己的部署 SOP。

6. 相依套件版本

  • jedi-auth 0.1.33 → 0.1.34（CM-1046 根因層修正：建立使用者不帶/帶 null org_units 時 500）。
  • 其餘 jedi-* 套件無版本變動。

7. FE 版本對齊

compliance-manager-fe package.json 同步 bump 至 1.14.0；本版 FE 主要變更：授權狀態頁、角色矩陣反灰、選單新增「授權管理」群組、向 LC 請照 dialog、檢測基準管理頁重構（拆六支子元件）與控制項詳細頁。

8. License Center（新增獨立系統，部署須知）

License Center 是本版新增的獨立部署單位，非本專案內建模組：

  • Repo：~/Projects/Billows/Audit-Manager/license_center/（獨立 DB，私鑰不出機，刻意與主產品分離）
  • DB 命名新標準：license_center_dev / license_center_stg（同 188 主機），license_center_poc（189 主機），皆 port 25432
  • 服務：systemd license-center.service，STG/POC 路徑 /opt/license_center，port 5062
  • 完整部署 SOP 見 LC repo docs/deployment-guide.html（以 STG 實戰部署為藍本）
  • 產品端與 LC 僅透過「簽好的 License 檔」或內部簽發 API（.10 新增）交互，無 DB 層共用

9. 部署順序與注意事項

  1. DB migration：依 §5 順序套用（三環境已完成）。
  2. License Center 先於產品 BE 部署：簽發鑰 keygen → 公鑰進 common/license/public_keys.py → BE commit 並 build → LC 起服務 → 建 API token → 請照實測，順序顛倒會導致「未知的 kid」。
  3. BE：git pull → 重啟（main_app.py）。
  4. FE：同版 build 部署。
  5. 執法總開關確認：LICENSE_ENFORCEMENT_ENABLED / LICENSE_READONLY_GATE_ENABLED 上線前確認符合預期（預設皆為 true）。
  6. root tenant 永不持照：root 無條件豁免執法，正式環境不應為 root 發照。
  7. 三環境公鑰共存不取代：新增 kid 不刪舊 kid，否則既有環境的照全部驗不過。

10. 已知限制與 follow-up

已知限制

  • License Center 目前皆內網部署（:5062），雲端公網（TLS／網域／防火牆）補驗尚待進行。
  • FR-060 url 型基準內容會靜默偏離來源：掃描抓的是 URL 即時內容，控制項明細是某次抽取的快照，git 上游改了平台不會自動感知。決策者已裁定方向（比對 ETag/Last-Modified 甲案），可行性未驗證，另案處理。
  • FR-060 三個欄位值仍是英文（檢查類型／適用角色／狀態），未決定是否翻譯。

Follow-up

  • design.md 缺 FR-062.9 段落：手動停權獨立欄位的設計決策未落文件，屬已知缺口。
  • STG 兩租戶正式發照：BE/LC 已就緒，發照動作由決策者手動執行（現有 2 張為部署驗證照）。
  • 正式環境簽發鑰：正式環境產出後必須先進 common/license/public_keys.py 才能 build 出貨 image。
  • CM-1143 遺留模組整鏈退役（cruise-project／resource／report＋jedi-resource-store）：Not started，全案後另議。
  • 未套的三支 migration（決策者裁示這次不動）：2026-07-20-ssp-shared-metadata-DEV-cleanup、2026-08-01-fr058-22-openscap-content-path-advanced（已被本版套用，另兩支仍待）、2026-08-03-fr060-1-detection-profile-split-advanced。
  • FR-060 舊表 detection_tool_profiles_deprecated_20260803 未 DROP：觀察期後另案處理。
  • FR-060 CM-1104：POC 12 支公版控制項抽取（管理員 UI 操作，非開發）。

11. 完整 changelog 索引

  • FR-062 設計文件：docs/features/FR-062-2608-license-management/design.md
  • FR-062 部署 SUMMARY（含 STG/POC 雙環境部署完整記錄）：docs/features/FR-062-2608-license-management/handoff/2026-08-10-fr062-deployment-SUMMARY.md
  • FR-062 STATE/LOG（living + append-only）：docs/features/FR-062-2608-license-management/handoff/fr062-STATE.md / fr062-LOG.md
  • FR-062 部署手冊：docs/features/FR-062-2608-license-management/v1.14.0-deployment-guide.md
  • FR-060 全案收尾 SUMMARY：docs/features/FR-060-2608-detection-profile-content-management/handoff/2026-08-03-fr060-arc-SUMMARY.md
  • FR-060 設計文件（D1–D19）：docs/features/FR-060-2608-detection-profile-content-management/design.md
  • License Center 部署手冊：license_center/docs/deployment-guide.html
  • License Center CLAUDE.md（架構守則、安全鐵律、與主產品介面）：license_center/CLAUDE.md
  • 授權管理使用指南（平台管理員 + 租戶使用者兩視角）：docs/user-manual/
  • 功能頁面 spec：docs/specs/current/ — License 授權管理／我的授權狀態頁面、system-admin/detection-profile-manage.md
  • Notion cases：CM-1054~1104（FR-060）、CM-1140~1183 一帶（FR-062 全案）

12. 相關文件索引

  • FR-062：docs/features/FR-062-2608-license-management/（design.md / discussion.md / handoff/）
  • FR-060：docs/features/FR-060-2608-detection-profile-content-management/（design.md / discussion.md / handoff/）
  • License Center repo：~/Projects/Billows/Audit-Manager/license_center/