手冊首頁 ／ Release Notes ／ Guidant AI v1.7.2 Release Note

Guidant AI v1.7.2 Release Note

項目 內容
版本 1.7.2（v1.7 收斂 arc 延續；主軸＝多租戶 tenant scope 資料模型 + 平台層 RBAC 三道防線）
發布日期 2026-06-30
上一版本 1.7.1（2026-06-28）
涵蓋區間 2026-06-29 ~ 2026-06-30
規模 3 個功能（多租戶 tenant scope 資料模型 / 平台層 capability 防護 / 合規框架寫入限平台層）+ DDD 分層稽核重構 + 流程範本內建唯讀，跨 BE + FE + jedi-auth + jedi-system-config + jedi-file-upload + jedi-flow-engine
適用部署 dev / staging / poc（9 支 migration 已全套）；prod 待
部署性質 非破壞性 schema（無 drop table/column），但含權限／行為變更（SMTP/LDAP/操作日誌/回饋整合/合規框架改平台層；多租戶 tenant_id=NULL 不變量）。含 9 支 DB migration + jedi-system-config 0.0.12 / jedi-auth 0.1.23 / jedi-file-upload 0.0.18 / jedi-flow-engine 0.0.32 pin。BE 需重啟生效。

1. 概述

v1.7.2 延續 v1.7 收斂 arc，主線是把多租戶資料模型與平台層權限收乾淨：

  • 多租戶 tenant scope 資料模型（FR-042 B-2）：消滅 tenant_id=NULL 這個壞語意，全域／公版資料改用「無 tenant_id 欄」或「scope 旗標 + 掛 ROOT(1)」表達；系統擁有者 admin 收編到 root tenant(1)，解掉 admin 建任何 tenant-scoped 資料失敗 / 落 null 孤兒的根因。
  • 平台層 capability 三道防線：新增 is_platform 概念，把 SMTP / LDAP / 操作日誌 / 回饋整合 鎖成「僅 root（平台層）租戶角色可持有」，租戶管理員無法再從角色矩陣把這些 capability 勾回租戶角色。
  • 合規框架寫入限平台層：合規框架（目錄 / 版本 / catalog / 匯入）為全域共用資源，改成「讀＝所有租戶、寫＝僅 root 租戶」。
  • DDD 分層稽核重構：SQL / ORM 一律收回 infra 層、infra session 取得統一走 @property/self.session，補齊分層規範。

版本定位 1.7.2（BUG 版號）：雖含數個功能項，整條屬 v1.7 多租戶收斂 arc，比照 v1.7.1 慣例走收斂版號。

2. 重點新功能 / 強化

2.1 多租戶 tenant scope 資料模型（FR-042 B-2）

  • 不變量：tenant_id IS NULL 一律視為壞資料 / 孤兒，不再賦予正常語意；新寫入不得落 null。
  • 系統擁有者 admin users.tenant_id NULL→1，補 user_tenants / user_org_units / Administrator role（root tenant/org_unit 各環境皆 id=1），修登入後空選單。
  • module_frames 補 scope（SYSTEM/TENANT，預設 TENANT）+ RLS：公版人人可讀、寫入 SYSTEM 限 super/admin（堵租戶偽造公版）。
  • flow_templates 4 筆 builtin 由 tenant_id NULL→1；SELECT policy 由 tenant_id IS NULL 改 is_builtin（搬 ROOT 後公版仍全租戶可見）。
  • SMTP / LDAP / system_configs（SMTP/LDAP/ISSUE/WEB_IDEL）改平台層共用，掛 ROOT(1)；新增 read_root_config_value() 繞 RLS 讀平台設定，common/constant/tenant.py SYSTEM_ROOT_TENANT_ID=1。
  • 完整決策見 docs/analysis/2026-06-29-tenant-scope-data-model.md；母案 Notion 38d346da-4cd0-812f-aba6-debcb1e1f632。

2.2 平台層 capability — 角色矩陣不可越權授予

三道防線（缺一不可）：

  1. 標記：capabilities 加 is_platform，標記 log.read / smtp-config / ldap-config / issue-integrate-config。
  2. 挑選端過濾：jedi-auth capability_service + BE UiRoutesRoute 對非平台 viewer 濾掉平台層 cap / route；FE RoleForm 依下拉選的租戶遞迴隱藏平台頁列。
  3. 寫入端硬擋：role_capabilities DB trigger trg_role_capabilities_platform_guard — 平台 cap 只能掛 root tenant 角色，非 root INSERT/UPDATE 平台 cap 直接擋（catch UI 繞過 / 直打 API / 直接 SQL）。
  • 連帶：回饋整合改平台層共用、順帶修 /tenants/menu 漏 parent_id。FR Notion 38e346da-4cd0-81bc-8120-c8a9d1175bb1。

2.3 合規框架寫入限平台層（讀＝所有租戶、寫＝僅 root）

  • BE：新增 common/util/permission.py（require_platform_admin()，委派 jedi-common _session_paths_have_root），合規框架寫入 app service 全面加守門共 17 處（framework / version / inline 編輯 / parse job）；新增 error code GRC_NOT_PLATFORM_ADMIN（GRC_403060）。
  • 資料：compliance-framework.create/update/delete 改 is_platform=true（read 維持 false）+ 清非 root 角色既有授予。
  • FE：合規框架 / 版本管理頁的新增 / 匯入 / 編輯 / 刪除入口僅平台租戶顯示；inline 編輯頁對非平台租戶唯讀；userStore.isPlatformAdmin getter 與 BE 同源。
  • Notion 38f346da-4cd0-8148-bace-d716854ee169。

2.4 DDD 分層稽核重構

  • SQL / ORM 查詢一律收回 infra 層（A1-A8 / B1 / C1-C2），route / app service 不再直接碰 ORM。
  • infra repo session 取得統一走 @property / self.session（機械批）。

3. 重要修補

  • 系統儲存設定 reader SessionLocal=None 修正：繞 RLS 讀 ROOT 平台設定時不可 from db import SessionLocal（綁 import-time None）→ 改 import 模組、呼叫時取 db.SessionLocal。
  • 流程範本內建唯讀：內建流程範本後端對所有人唯讀（_guard_not_builtin），但列表「編輯」鉛筆對內建仍啟用 → FE 改 v-if="!data.is_builtin" 直接不顯示編輯 / 刪除入口，名稱點擊內建改開預覽（保留預覽 / 複製，客製化走「複製成自訂再改」）。Notion 38f346da-4cd0-8177-bb06-e9d189c08679。

4. Breaking Changes / 行為變更

schema 層非破壞（無 drop table / column），但下列為權限 / 行為變更，升級後相關角色行為會改變：

  • SMTP / LDAP / 操作日誌 / 回饋整合 改平台層：非 root 租戶角色不再能持有或在角色矩陣勾選這些 capability；per-tenant SMTP / 回饋整合設定已清，改讀 ROOT 平台共用設定。
  • 合規框架寫入限 root 租戶：非 root 租戶對合規框架的新增 / 編輯 / 刪除 / 匯入一律 403（GRC_403060），只保留瀏覽。
  • tenant_id=NULL 不再合法：全域 / 公版資料改掛 ROOT(1) 或用 scope 旗標；既有 null 列已由 migration 收編 / 清除。

5. DB Migration

本版含 9 支 migration（全部 dev / stg / poc 已套並登錄 schema_migrations，prod 待）：

# 檔案 內容
1 2026-06-29-b2-admin-root-tenant.sql admin tenant_id NULL→1 + user_tenants / user_org_units
2 2026-06-29-b2-admin-root-tenant-roles.sql admin Administrator role / user_role 由 global 轉 tenant=1
3 2026-06-29-fr042-tenant-scope-module-frames-flow-templates.sql module_frames 加 scope + RLS；flow_templates builtin→ROOT、policy 改 is_builtin
4 2026-06-29-system-configs-null-to-root.sql 5 筆 null system_configs → 掛 ROOT(1)
5 2026-06-29-smtp-platform-only-drop-per-tenant.sql SMTP 改平台共用，刪非 ROOT per-tenant SMTP
6 2026-06-29-platform-only-smtp-ldap-log-capabilities.sql 非平台角色移除 smtp/ldap/log capability
7 2026-06-29-platform-capability-flag-and-guard.sql capabilities 加 is_platform + role_capabilities 寫入 trigger
8 2026-06-29-cleanup-orphan-projects-and-test-root-tenant.sql 清 17 筆孤兒 projects + 測試 root tenant 134/135
9 2026-06-30-compliance-framework-platform-capability.sql compliance-framework 寫入 cap 改 is_platform=true + 清非 root 授予

執行：psql --single-transaction -v ON_ERROR_STOP=1 -f <檔>，帳號 cmmgr。

6. 相依套件版本

本版較 v1.7.1 異動的 jedi-* pin：

套件 版本 說明
jedi-system-config 0.0.12 get_by_group_and_key 加 tenant scope + order_by(id) 確定性
jedi-auth 0.1.23 capability_service 平台層過濾、tenant menu parent_id
jedi-file-upload 0.0.18 （隨批 pin）
jedi-flow-engine 0.0.32 （隨批 pin）

其餘 jedi-* 維持 v1.7.1 既有 pin（jedi-common 0.0.26 / jedi-oscal-v2 2.1.0 等）。

7. 部署順序

  1. DB migration（prod）：依 §5 表格順序 1→9 各跑（dev/stg/poc 已套）。
  2. BE：poetry update（拉 jedi-system-config 0.0.12 / jedi-auth 0.1.23 / jedi-file-upload 0.0.18 / jedi-flow-engine 0.0.32）後重啟（無 hot reload）。
  3. FE：build + 部署（版號對齊 1.7.2）。
  4. 驗證：非 root 租戶登入 → 合規框架 / 流程範本內建只可瀏覽、編輯入口不顯示；角色矩陣看不到平台層 capability；root 租戶一切照常。

8. 已知 follow-up

  • prod migration 未套：本版 9 支 migration 僅 dev/stg/poc 已套，prod 待部署時程。
  • RLS session_scope else 段：無 context 暫開 is_super_admin='t'，待盤點觸發情境後收緊（沿用既有 follow-up）。

9. 完整 changelog 索引（v1.7.1 之後）

  • docs/changelog/2026-06-29-feat-tenant-scope-data-model-b2.md
  • docs/changelog/2026-06-29-feat-platform-only-capability-guard.md
  • docs/changelog/2026-06-29-fix-system-storage-reader-sessionlocal-none.md
  • docs/changelog/2026-06-30-feat-compliance-framework-platform-write.md
  • docs/changelog/2026-06-30-fix-flow-template-builtin-hide-edit.md

10. 相關文件索引

  • docs/analysis/2026-06-29-tenant-scope-data-model.md（tenant scope 設計決策）
  • docs/features/FR-042-*（tenant scope / 分層稽核）
  • Notion：母案 38d346da-4cd0-812f-aba6-debcb1e1f632、平台 capability 38e346da-4cd0-81bc-8120-c8a9d1175bb1、合規框架 38f346da-4cd0-8148-bace-d716854ee169、流程範本 38f346da-4cd0-8177-bb06-e9d189c08679
Guidant AI 功能 SPEC 手冊 v1.9.0｜本頁由 render_html.py 產生，內容源：specs/v1.9.0/release-notes/v1.7.2.md