跳轉到

Guidant AI v1.20.0 Release Note

項目 內容
版本 1.20.0（功能版號；主軸＝後端套件體系收整＋出貨升級鏈補齊＋租戶隔離修正——FR-080／089／090／091／092／093／094／096 八個 arc 一次收口）
發布日期 2026-09-15
上一版本 1.19.0（2026-09-03）
涵蓋區間 2026-09-03 ~ 2026-09-15（c1fb2397..bd0f65d7，BE 466 commits：docs 309／fix 34／refactor 32／chore 24／feat 22／test 15／security 2／perf 2；FE 21 commits；jedi monorepo 262 commits）
涵蓋需求 FR-080 jedi 整併與服務化（25 支收成 21 支、分五層、依賴只准往下）／FR-089 套件結構統一（以 jedi-asset 定形）／FR-090 主專案側殘留收斂（接線收成 core/plugins/<pkg>.py 一支一檔）／FR-091 21 支套件套用標準形狀／FR-092 廢碼清理／FR-093 出貨升級鏈補齊（D1–D8）／FR-094 租戶隔離修正（RLS 第三波＋「分享給子租戶」開關）／FR-096 租戶邊界與顯示正確性前端修正。另含 FR-075～088、095 資安掃描報告文件（掃描結果的修正不含在本版，決策者裁）
規模 jedi- 套件 21 支統一版號 1.1.0，其中八支因後續修正進 1.1.2、兩支 1.1.1*（jedi-oscal-v2 走自身序列 2.4.0），全數已推 Nexus；主專案廢碼淨刪 73 檔約 6,300 行＋12 支端點退役＋FE 15 檔備份頁清除；主線 DB migration manifest 異動 29 列（22 支新增＋4 支既有改為全環境套用）；套件自帶 SQL 46 支；能力點宣告 127 筆
適用部署 188 STG ＋ 189 POC（安裝版 docker stack，install.sh --upgrade）。190 e2e 測試機已完成兩路驗證（乾淨新裝＋模擬舊機升級，CM-1778）＋ 預發版 beta.1／beta.2 實機手測通過
部署性質 含大量 DB 結構變更：RLS（資料庫層的租戶隔離）開啟 30+ 張表、孤兒表 drop、套件 SQL 首次由升級鏈自動套用。升級前務必確認已備份（install.sh --upgrade 會自動備份並印出還原指令）

0. 發版前回歸 gate

  • 機器驗證：各 arc 收口時全量 pytest 綠＋守衛測試綠（模組邊界／凍結 URL／凍結 error code／能力點對 seed 零未歸類／碼表複本完整／碼表撞號）；FR-080／089／090／091 各做過 arc review，Critical／Important 全修。
  • e2e 測試機兩路驗證（CM-1778）：① 乾淨 docker 從零新裝，驗 DB 初始化＋套件 SQL 攤平＋能力點 upsert；② 拿舊版快照模擬客戶升級，驗 migration 與套件 SQL 順序套用、RLS 開啟後登入／切租戶／我的任務／兩支凌晨排程都還活著。比對結果：資料庫結構 16904 行相同、權限 4188 行零差異、RLS 461 條零差異、migration 紀錄 211 筆零差異、能力點零差異。該輪抓到並修掉一處真缺陷（內建流程範本 scope 兩路不一致，新裝客戶看不到內建流程）。
  • 預發版實機手測：beta.1／beta.2 先後部署 190，決策者逐項手測；beta.2 的五件修正（角色權限勾選三種身分、切換租戶、控制項樹標題）全數通過。
  • site-regression 自動 gate 依 v1.16.0 以來慣例暫緩，由測試機手測補位。

1. 概述

v1.19.0 把後端拆成 25 支 jedi- 套件，本版是拆完之後的收整與補洞*，分三條線：

  1. 套件體系定形（FR-080／089／090／091／092）：25 支合併成 21 支、分五層（基座→橫切→平台服務→平台骨架→業務）且依賴只准往下；每支套件長一樣的形狀（plugin/ 五檔、api/ 拆守門與路由、取執行期組件一律叫 runtime()）；主專案側接線收成 core/plugins/<pkg>.py 一支一檔；順手清掉從入口走不到的 73 檔廢碼與 12 支三方都沒人打的端點。對外 API 契約全程凍結（URL、error code 字串值零漂移），前端無感。
  2. 出貨升級鏈補齊（FR-093）：以前套件會自己宣告「我需要哪些表、哪些權限」，但安裝包與升級腳本完全不讀這兩份宣告——新版裝上去功能在、表沒建、管理員點進去 403 且沒任何錯誤訊息。本版讓 build 期把 21 支套件的 SQL 攤平進安裝包、升級時自動套；能力點（權限點）宣告 115 筆升級時自動寫進資料庫並補給管理員角色；公版流程、階段字典等「既有客戶升級才補得到」的預設值由 seed 改成 migration。
  3. 租戶隔離修正（FR-094）：FR-087 資安盤點查出 13 張表、4 支 view 的 RLS（Row Level Security，資料庫自己擋、讓每個客戶只查得到自己的資料）實際上是關的——決策者親測切到子租戶後仍看得到別家待辦 39 筆、專案 213 筆。本版逐張補規則並打開，另修排程「無身分＝超級管理員」的洞，新增母租戶把自訂資源「分享給子租戶」的開關。

2. 使用者可見變更

  • 租戶隔離收緊（FR-094）：專案、POA&M、任務執行紀錄、問卷 12 張表、授權關聯表（角色指派／租戶隸屬／部門隸屬）、雲端硬碟串接設定等 30+ 張表開啟資料庫層隔離。切到子租戶後只看得到該租戶的資料；平台管理員不受影響。
  • 「分享給子租戶」開關（FR-094.4b／4c，CM-1790／1798）：模組框架、流程範本、檢測方案、任務範本四個編輯頁多一個開關——母租戶自訂的資源打開後子租戶可讀（唯讀，不能改）。模組框架與流程範本的 API 回應新增 tenant_id 欄位，前端據此判斷是不是自己租戶的資源。
  • 部門不再是牆（FR-094 原則③）：任務執行與流程範本的查詢／更新規則去掉部門條件（DEV 實查 68% 任務指派跨部門，照舊規則開隔離會讓跨部門推進任務「更新 0 筆不報錯」）。可見度靠角色與參與關係，部門只記歸屬。
  • 切到被指派的子租戶後權限全空（CM-1661／1664）：本人帳號落在父租戶、在子租戶查不到自己，導致權限查詢回零列。使用者資料表補「本人恆可見」例外。
  • 待辦任務列表不再把檢測任務降級成「一般」（CM-1658）；任務問卷的設備兩欄改走名冊接口，不再讀已拆掉的欄位（CM-1656）。
  • 12 支端點退役（FR-092）：前端、檢測 Agent、e2e 三方都沒人打的端點下線，含 subtask_status_history 整個模組；FE views/_archived/ 15 檔備份頁一併清除。
  • 資安修補零星幾條（來自 v1.19 後的 FR-076 掃描結論）：授權租戶重複用照擋 TOCTOU（CM-1580）、人為停權移到租戶層換照不再清掉（CM-1579）、全站請求大小上限 50MB（CM-1587）、LDAP 連線測試改位址時強制重輸密碼（CM-1564）。
  • 意見回饋的功能分類改由頁面路由表重建（FR-093.4d）——升級後新頁面才會出現在回饋分類裡。

租戶邊界與顯示正確性修正（FR-096）

  • 新增角色勾「合規框架」不再存檔失敗（CM-1801）：該功能的四個動作被切在兩層——「檢視」一般租戶可給，「新增／修改／刪除」屬原廠保留、只有最上層租戶的角色能持有。前端照功能分組勾選時把整組送出，後三個被資料庫規則擋下。權限模型維持現狀（合規框架由系統釋出、不由使用者自行維護），改為前端只送「這個角色收得下」的項目：判準是我自己拿不拿得到、且正在編輯的角色收不收得下，兩條缺一不可。連帶補上一個更隱蔽的洞——最上層管理員替子租戶建角色時，後端會把平台層權限全數回給他（他自己確實有資格持有），但資料庫規則判的是「角色屬哪個租戶」而非「誰在操作」，照樣會失敗。
  • 切換租戶後回到首頁（CM-1801）：原本原地重整，停在詳細頁時網址帶著舊租戶的資料編號，重整後查不到而報錯——那是租戶隔離正常運作的結果，但使用者只看到錯誤。另補：切換失敗時完整還原身分並提示；切換語系不再讓租戶選單長出重複項目。
  • 合規資源庫控制項樹群組標題不再顯示 null（CM-1801）：控制項目錄的群組本無描述欄位，前端組標題時把空值直接印出。兩支畫面同因一併修正。
  • 錯誤碼撞號正名（CM-1802）：三個錯誤碼原本被兩個語意不同的情況共用，前端只認字串、因此只能顯示其中一句（例如改分享設定被擋卻顯示「無權切換至該租戶」）。主專案側改開新號，訊息與動作對上。另兩個碼因已寫進 v1.8.0 交付文件而維持原狀、只補註解說明代價。新增守衛擋未來再撞——主專案與 21 支套件各自管號段、互相看不見，撞號是系統性的而非個別疏失。
  • 套件碼表清理（CM-1802）：刪除 jedi-log 中 71 個零引用的上古錯誤碼（留著的風險是被誤認為現役而使用，其值與主專案不同）；jedi-remote-agent 指向已刪目錄的過期註解改寫。

3. 內部重構重點（工程視角）

  • FR-080：四組合併（資產＝device＋information-system、任務平台吞 participant、系統核心＝system-config＋system-menu、日誌吞 log-forwarding）；五支「有殼沒肉」補實四支（bulletin／device／information-system／system-config，flow-engine 留待 CM-1478）；跨套件直接 import 改走接口；宿主顯式決定 OTel 遙測（預設不啟用）。
  • FR-089／091：jedi-asset 定形寫進 SOP §4.3，18 支套用；identity port 只給有吐 created_user_name 的套件；enum 值域統一小寫修好「五個系統狀態只有兩個存得進去」的真 bug（CM-1678）。
  • FR-090：空殼清理、port 實作歸位 infra/<pkg>/、iam 宿主側收成 infra/iam/＋core/iam_wiring.py、補審計暱稱統一走 D8；主專案自有 36 筆能力點開申報處。DI 瘦身走 B 案並已落地（CM-1696 三子卡）：套件開 host_services() 取用口、主專案 39 處改走取用口、兩條守衛擋回流（di_containers/ 不得自建套件 service、不得直指套件 container），教學文件同步改寫。
  • jedi-common 1.1.0 新 export：system_context／tenant_context／elevated_session／fill_user_names；18 支套件下限提到 >=1.1.0。排程改用具名系統身分繞 RLS（FR-094.1a／1b，CM-1767／1787），Drive webhook 與 OAuth 回呼接上租戶身分（CM-1788）。
  • FR-093 D1–D8：flatten_pkg_migrations.sh 攤平套件 SQL、migrate.sh 三輪（主線→套件差集→能力點 upsert＋角色回補）、既有庫一次性補登 23 支套件 migration、99-stamp 只蓋結構類不蓋資料類與套件 SQL（CM-1792）、六支被誤標 dev 的結構變更改 * 並補進出貨基線（CM-1655／1664）。長期規則：套件疆界的表只在套件改，主專案 scripts/sql/ 不再新增套件表的 migration。
  • 詳帳見各 docs/features/FR-08x／FR-09x/README.md 與母卡（FR-080 CM-1618 群、FR-089 CM-1676～1678、FR-090 CM-1682、FR-092、FR-093 CM-1752、FR-094）。

4. Breaking Changes

  • 對外 API：12 支端點退役（FR-092，三方零呼叫者）；其餘 URL／error code 字串值零漂移。
  • 資料可見範圍：RLS 開啟後，原本靠「隔離沒開」而看得到別租戶資料的帳號會看不到了——這是修 bug 不是功能倒退，但客戶若有跨租戶指派的既有資料要注意（本版 SPEC 已寫明不支援跨租戶指派）。
  • 內部：jedi-* 25→21 支，合併掉的套件（participant／information-system／system-config／system-menu／log-forwarding）import 路徑已變；主專案側一律從 core/plugins/<pkg>.py 掛載；ctx() 改名 runtime()。
  • 出貨線：安裝包從本版起必須用 1.1.0 套件 build（2026-09-13-cm1765-drop-operations-and-device-mapping 與套件 associations 鏈同批收斂，套件未發出前不可套）。

5. DB Migration

主線（scripts/sql/manifest.tsv 異動 29 列：22 支新增＋4 支既有改標 *）

FR-069 既有四支由 dev 改 *（CM-1655／1664）：fr069-17-drop-users-topt-secret／fr069-cm1474-drop-assessment-plan-extensions／fr069-cm1474-drop-project-extensions／fr069-cm1490-soft-ref-job-execution-bindings——結構變更每個環境都需要，原標 dev 讓客戶裝機沒有、升級也補不上；已補進出貨基線庫。

資安修補（FR-076） - 2026-09-06-cm1580-tenant-licenses-license-id-partial-unique：授權表加部分唯一索引，擋跨租戶重複用照。 - 2026-09-06-cm1579-tenant-license-suspensions：新表，人為停權語意從授權列移到租戶層。

FR-080 - 2026-09-10-fr080-cm1624-participant-project-fks：人員指派併入任務平台後補回六張表的 project_id 外鍵＋清 36 筆孤兒。 - 2026-09-10-fr080-cm1625-bulletin-org-units-soft-ref：公告部門橋表外鍵改軟參照。 - 2026-09-11-cm1661-users-rls-self-visible／2026-09-12-cm1664-users-rls-self-visible-textcmp：使用者表補「本人恆可見」，第二支修簽章憑證路徑不帶使用者編號時 ::int 炸 500。

FR-092 廢碼清理 - 2026-09-13-cm1723-drop-orphan-tables：drop 14 張零引用零資料孤兒表。 - 2026-09-13-cm1765-drop-operations-and-device-mapping：drop operations＋兩張設備關聯表。 - 2026-09-13-cm1723-drop-dev-only-backup-tables／2026-09-13-cm1765-drop-system-logs-old（僅 dev）：DEV 專屬備份表與舊日誌表。

FR-093 升級鏈 - 2026-09-13-fr093-1-backfill-package-migrations：既有庫一次性補登 23 支套件 migration 檔名（必須在套件差集之前執行）。 - 2026-09-14-fr093-4d-flow-templates-stage-objects（seed）：公版稽核流程 2 筆＋階段字典 6 筆＋兩列單例設定，由 seed 改 migration。 - 2026-09-14-fr093-4d-function-labels-from-ui-routes（seed）：意見回饋功能分類依路由表重建。

FR-094 租戶隔離 - cm1768-enable-rls-projects-drive-integrations：專案表補超級管理員分支並開 RLS；雲端硬碟串接設定開 RLS。 - cm1769-rls-user-roles-tenants-org-units：三張授權關聯表補 policy 並開 RLS。 - cm1770-rls-poams-evidence-jobs-parse-jobs：POA&M／證據分類兩張／任務執行／框架解析五張表開 RLS。 - cm1771-rls-workflow-executions-view-security-invoker：任務執行表去部門條件並開 RLS；兩支 view 改 security_invoker（不再以擁有者身分繞過隔離）、兩支零讀者 view drop。 - cm1772-workflow-templates-scope-rls：流程範本加 scope、清無主凍結副本、去部門條件、開 RLS。 - cm1773-rls-survey-12-tables：問卷 12 張裸表補 JOIN-based policy 並開 RLS＋13 支外鍵索引。 - cm1790-shared-scope-subtree：scope 值域加 SHARED＋反向前綴 helper，五張表 select 加「母租戶分享」分支（行序必須在 cm1772 之後）。 - cm1796-question-answers-backfill：作答表捷徑欄位回填＋補 CASCADE 外鍵。 - cm1794-dev-fix-table-owners（僅 dev）：DEV 19 張表擁有者由 cm_app 改回 cmmgr（表擁有者不受 RLS 約束，改前是假綠）。

套件自帶 SQL（scripts/sql/packages/manifest.tsv，44 支）

build 期由 flatten_pkg_migrations.sh 攤平進安裝包，升級時 migrate.sh 第二輪套差集；第三輪把 115 筆能力點宣告自動 upsert 並回補管理員角色。這是本版第一次走這條鏈，e2e 測試機兩路驗證即為其 gate。

6. 已知 follow-up

  • GET /feedback 回 500（既有問題，非本版引入）。
  • /audit-round/<uid>/{launch-audit, start-auditing, ar/finalize, ap/generate-draft} 四支端點前端零呼叫、只有 e2e step 在打——是前端漏做還是流程改走別路未定，待開卡裁決後退役。
  • 資安掃描總表 12 項待決策者裁（修正另開 arc，不進 1.20.0）。
  • jedi-flow-engine 的 pyproject.toml 未宣告 jedi-common 相依（目前靠主專案間接帶入，單獨安裝會缺）。
  • flow-engine 套件內死程式與主專案複製出去的執行服務未收（等 CM-1478 流程疆界設計）。
  • 前端簡體中文錯誤訊息翻譯檔僅 92 條（繁中與英文各 638 條），簡體使用者碰到多數錯誤會看到原始碼字串。長期缺口，待裁是否補齊。
  • 錯誤碼正名後 docs/api/uploadfile/api-spec.md 與 spec-site 三頁仍寫舊碼，待 SPEC 同步。

7. 部署順序

  1. STG（188） install.sh --upgrade → 觀察六服務健康、登入、切租戶、我的任務。
  2. 確認無誤後 POC（189） 同步驟。POC 等同 production（對外 demo／客戶試玩），務必在 STG 驗過再上。
  3. 升級腳本會自動備份資料庫並印出還原指令；回滾為災難逃生用，會丟失升級後產生的資料。

8. 交付包注意

目前的出貨包缺正式環境（PROD）授權簽發公鑰——該鑰尚未建立（非故障，套件內現有 dev／stg／poc 三把）。要產出可交付客戶的安裝包需另行四步：授權中心端產正式簽發鑰 → 加進 jedi-license-runtime 的公鑰表 → 發版 → 重新 build。在此之前產出的包僅供內部環境使用。