套件宣告的表、權限、選單，在客戶升級時自動到位

狀態：設計定案（D1–D8 已拍板，2026-09-13）｜前作：FR-089、FR-091（前置三卡 CM-1728～1730）、FR-092｜討論稿：discussion.html

FR-089／FR-091 之後，21 支 jedi-* 套件都有標準形狀，其中兩樣東西跟資料庫有關：migration（套件自帶 SQL，宣告「我需要哪些表」）與能力點（CAPABILITIES 常數，宣告「我的端點用哪些權限名稱守門」）。今天這兩份宣告都沒有任何一條路送進客戶的資料庫：

同一批套件表另有一份「真正的 DDL」在主專案 scripts/sql/（41 支，已收進 02-schema.sql），兩份已漂移（detection 缺 7 FK、enum 大小寫）。本案把「套件宣告 → 出貨 bundle → 客戶升級 → 資料庫到位」這條鏈補齊，並定下長期規則 D3：套件疆界的表往後只在套件改。

目標鏈（補齊後）

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant W as 套件 wheel（site-packages）
    participant B as build_release.sh／build_init_image.sh
    participant I as init image（migrate 模式）
    participant D as 客戶 DB

    B->>W: 掃 <pkg>/migrations/*.sql ＋ CAPABILITIES 宣告
    B->>B: 攤平到 /opt/guidant/sql/packages/<pkg>/ ＋ 產套件子清單 ＋ 宣告對照 _capabilities.sql
    B->>B: stamp gate：wheel 檔案集合 ＝ 攤平集合 ＝ 99-stamp 清單，不一致 build fail
    B->>I: COPY 整個 /opt/guidant/sql（主線＋packages/）
    Note over I,D: 客戶執行 install.sh --upgrade
    I->>D: SELECT filename FROM schema_migrations
    I->>I: 差集①：主 manifest active/*（既有行為）
    I->>D: 套主線待套檔（psql --single-transaction）＋ INSERT schema_migrations
    I->>I: 差集②：packages/<pkg>/NNN-*.sql 依套件名字母序、套件內序號序
    I->>D: 套套件待套檔（每支 SQL 冪等）＋ INSERT 'packages/<pkg>/NNN-*.sql'
    I->>D: upsert capabilities by name（宣告對照 → INSERT ... ON CONFLICT (name) DO UPDATE description/is_platform）
    I->>D: 回補 role_capabilities：root Administrator 補齊全部；租戶管理員照基準角色補，NOT is_platform ＋ licensed_modules 扣除
    D-->>I: 完成，印出「主線 N 支／套件 M 支／能力點新增 K 筆／回補角色 R 個」

整案一句話：讓套件宣告的「需要哪些表」與「需要哪些權限、哪些選單」在客戶升級時自動到位——出貨線讀套件 migration、升級時補能力點與角色授權、每支新頁面必綁權限。

依賴一句：.1 是地基（.2／.3 的 SQL 要走 .1 的線出貨）；.2 不動套件源碼，可與 .3 平行；.3 動 jedi-*，發版在 .1 驗通之後、等令。

5.1 階段 1：出貨線接套件 migration

① build_release.sh：攤平套件 migration（build 期產物，不入版控）

• 不用 PKG_DATA_DIRS 白名單（它是「複製到 BE 產物目錄」的機制，目標是 BE image；migration 的目標是 init image 的 /opt/guidant/sql/），新增獨立函式 flatten_pkg_migrations <目標目錄>：
  1. 取 sysconfig.get_paths()["purelib"]，glob */migrations/*.sql（只掃 jedi_* 前綴目錄，避免撈到第三方套件）。
  2. 每支複製到 <目標目錄>/packages/<pkg import 名>/<原檔名>（<pkg> 用 import 名如 jedi_asset，與 site-packages 目錄名一致，避免 dist name／import name 兩套）。
  3. 同時產 <目標目錄>/packages/manifest.tsv（套件子清單），格式與主 manifest 同四欄，每列：packages/<pkg>/NNN-xxx.sql<TAB>active<TAB>*<TAB>auto-generated from <dist-name> <version>；行序＝套件 import 名字母序、套件內檔名序（LC_ALL=C sort）。
• 產物落點：scripts/sql/packages/——.gitignore 排除，不入版控、build 期產生。理由：它是 wheel 的鏡像，入版控就變成第三份 DDL；但 build_init_image.sh（跑在 repo 根、COPY context 是 $REPO_ROOT）與 assert_db_current.sh 要讀得到它，所以攤平動作要在 build_init_image.sh 前置段也能單獨觸發（抽成 scripts/build/flatten_pkg_migrations.sh，兩支 build 腳本共用；build_all.sh 只跑一次）。
• 攤平時對每支 SQL 做靜態檢查：檔名符合 ^\d{3}-[a-z0-9-]+\.sql$；不含 INSERT INTO public.schema_migrations（套件 SQL 不自登記，由 migrate.sh 統一登記相對路徑檔名，否則主鍵會登成裸檔名而再撞）。不符即 build fail。

② 套件子清單格式

同主 manifest 四欄；phase 固定 active、envs 固定 *（套件沒有「原廠內部環境限定」的概念）。migrate.sh 讀它時走同一段解析程式碼（抽成函式 read_manifest <檔> <陣列名>），差別只在 filename 帶 packages/ 前綴。

③ docker/init/Dockerfile

COPY scripts/sql/ /opt/guidant/sql/ 已會把 scripts/sql/packages/ 一併帶入（子目錄）；不需新增 COPY 行，但要在 Dockerfile 加一行斷言 RUN test -f /opt/guidant/sql/packages/manifest.tsv——沒先跑攤平就 build image 要當場 fail，不能出一顆「主線正常、套件段空白」的 init image。

④ migrate.sh 第二輪差集

• 第一輪（主線）完全不動。
• 主線套完（或待套 0）後：讀 ${SQL_DIR}/packages/manifest.tsv（缺檔 → die 1 "出貨包不完整"），算差集 PENDING_PKG，印「套件待套 M 支」，同樣 dry-run／APPLY 兩段。
• 套用迴圈與登記共用第一輪的程式碼（apply_one <相對路徑>），登記值就是 packages/<pkg>/NNN-xxx.sql。
• 核對過的過濾行為：:86 的 grep -v '^__' | grep '\.sql$' 對 packages/jedi_asset/002-asset-rls-grants.sql 過得去；grep -qxF 全字比對相對路徑也正確。哨兵 __init_baseline_* 不受影響。
• 既有客戶庫保護：第二輪前若 schema_migrations 內 packages/% 筆數為 0 且 PENDING_PKG 等於子清單全量，印警告「套件段從未登記過，將全數重放；請確認本版主線已含補登 SQL」——不擋（補登 SQL 在主線先跑，跑完就不會是 0），只是讓人看得到。

⑤ stamp gate 與 assert_db_current.sh

• build_init_image.sh：現有 diff 改成兩張：主 manifest active/* ↔︎ stamp 內無 packages/ 前綴的列；套件子清單 ↔︎ stamp 內 packages/ 前綴的列。任一不一致 fail，訊息分開印。另加第三道：wheel 內實際檔案集合（重新 glob site-packages）↔︎ 攤平集合，抓「攤平產物 stale」。
• gen_stamp_sql.sh：補登段多讀套件子清單，同樣標 converged into __init_baseline_v<版>__。
• assert_db_current.sh:174-199：tmp_expect 併入套件子清單；訊息「落後 N 支」分主線／套件兩個數字。

⑥ 既有庫一次性補登

• 一支主線 migration scripts/sql/2026-09-<日>-fr093-1-backfill-package-migrations.sql，走 sql-migration skill 全部規範（檔頭 -- Date:、語句日期註解、收尾 INSERT schema_migrations）。內容：24 列 INSERT INTO public.schema_migrations(filename, note) VALUES ('packages/<pkg>/NNN-xxx.sql', 'FR-093.1 backfill：表已由 02-schema.sql／主線 migration 建立，converged into __init_baseline_v1.19.0__') ON CONFLICT (filename) DO NOTHING。
• 這支登在主 manifest（active／*），所以升級時走第一輪、在第二輪套件差集之前執行——這是 D2 排序的用意。
• CM-1678 那一支例外不補登：packages/jedi_asset/002-asset-rls-grants.sql 從補登清單排除，讓它成為第二輪唯一待套的檔，真的套進 DEV。
• 環境：先 DEV（localhost:5432）；STG／POC 與已出貨客戶等放行（環境鐵律）。
• 新裝路徑：99-stamp.sql 由 gen_stamp 產、已含 24 支（含 002），新裝機不會重放。

⑦ 首次真實驗收案：CM-1678 enum 修正（jedi-asset 002）

• 已核：wheel 1.0.1 內的 002-asset-rls-grants.sql:120-146 已經是冪等寫法（DO $$ ... IF EXISTS (SELECT 1 FROM pg_enum ...) THEN ALTER TYPE ... RENAME VALUE），在已是小寫的庫上會跳過、不會 enum label already exists。階段 1 不必先改套件，直接用 1.0.1 驗。
• 仍要親眼驗的兩件事：(a) 新裝路徑：02-schema.sql:116-133 建出大寫型別 → 第二輪套 002 改成小寫，終態與升級路徑一致（\dT+ compliance.system_status_enum 兩條路都是小寫）；(b) RENAME VALUE 後同一交易內不能使用新值——002 檔內 enum 段之後不得有用到新值的 INSERT／UPDATE，核對一次。
• 驗收指令：DEV 套完 → \dT+ compliance.system_status_enum、\dT+ compliance.security_sensitivity_level_enum 全小寫；SELECT filename FROM schema_migrations WHERE filename LIKE 'packages/%' 得 24 支（23 補登＋1 實套）。

5.2 階段 2：seed name-based＋能力點 upsert＋角色回補

① 04-seed-core.sql 四段改 name 反查（gen_seed_sql.sh 後處理）

比照 LABELS_SECTION 的做法：這四張表不再 pg_dump（從 dump 表清單移除），改由產生器內建模板從基線庫 SELECT 出資料後產成邏輯 SQL：

• 產生器內的 setval 段對這四張表照舊（sequence 仍要推進）。
• 驗證段（gen_seed_sql.sh:333-381 那個 DO $$）加四項筆數斷言：capabilities 筆數＝模板筆數、role 2 持有數＝capabilities 總數、每筆 route_capabilities 的 route_id／capability_id 都反查得到。
• ui_routes 子節點的 id 不再寫死，因此 labels 段（D11.5 由 ui_routes 重建）不受影響（它本來就用 name）。

② 能力點宣告攤平：scripts/sql/packages/_capabilities.sql（build 期產）

• 攤平腳本（與 5.1① 同一支 flatten_pkg_migrations.sh，多一段）用 $VPY -c 載入 21 支套件的 <pkg>.plugin.CAPABILITIES＋主專案宣告（CM-1748 落地後的位置，開卡前確認，見 §8），產：

-- 由 flatten_pkg_migrations.sh 自 CAPABILITIES 宣告產生，勿手改
SET LOCAL app.is_super_admin = 't';
INSERT INTO public.capabilities (name, resource_type, action, description, is_platform) VALUES
  ('device.create', 'device', 'create', 'device create access', FALSE),
  ...
ON CONFLICT (name) DO UPDATE
  SET description = EXCLUDED.description,
      is_platform = EXCLUDED.is_platform;

• 檔名以 _ 開頭是刻意的：它不進套件子清單、不登 schema_migrations（每次升級都要跑，不是一次性 migration）。攤平時的重複 name 檢查：兩支套件宣告同名能力點 → build fail。
• is_platform 直接取 Capability.is_platform（jedi_common/plugin/capability.py:46-51，預設 False）；dataclass 另有 default_roles（預設 Administrator），本案不消費它——授權走 D6 的參照角色法，不由套件決定角色名。

③ 角色回補 SQL：scripts/init/migrate-capability-grants.sql（入版控、固定內容）

每次升級在 _capabilities.sql 之後執行，兩段：

• root Administrator 補齊：定位用 roles.tenant_id=1 AND name='Administrator' AND is_delete=0（不用 is_admin=1：同一理由，客戶在 root 租戶自訂的管理角色不該被當 Administrator）。INSERT INTO role_capabilities SELECT r.id, c.id FROM roles r CROSS JOIN capabilities c WHERE <定位> ON CONFLICT DO NOTHING——含 is_platform 能力點（root 租戶可持有）。
• 租戶管理員參照角色法：基準能力點 flow_template.create（比照 fr059-2；它是每個租戶 System Manager 建立時必得的租戶級能力點）。凡持有它、且 roles.tenant_id <> 1 的角色，補「該角色尚未持有」的能力點，三道扣除在 SQL 內表達：

INSERT INTO public.role_capabilities (role_id, capability_id)
SELECT r.role_id, c.id
  FROM (SELECT DISTINCT rc.role_id FROM role_capabilities rc
          JOIN capabilities b ON b.id = rc.capability_id
          JOIN roles ro ON ro.id = rc.role_id
         WHERE b.name = 'flow_template.create' AND ro.tenant_id <> 1 AND ro.is_delete = 0) r
 CROSS JOIN public.capabilities c
 WHERE NOT c.is_platform                                              -- 扣除②
   AND c.resource_type NOT IN ('cruise-project','dashboard','workflow','resource','report')  -- 扣除①
   AND c.resource_type = ANY (:licensed_resource_types)               -- 扣除③
ON CONFLICT (role_id, capability_id) DO NOTHING;

• 扣除①：TENANT_ADMIN_EXCLUDED_RESOURCE_TYPES（core/plugins/identity.py:89-95）的五個值由攤平腳本從 Python 常數讀出後注入，不在 SQL 手抄（兩份會漂移）。
• 扣除③ licensed_modules 在 SQL 表達不了：授權模組是從租戶現行照（config.tenant_licenses 的解析快取）算出來的集合，且 provisioning 時「無照＝不扣」（ProvisioningLicensedModules，identity.py:275-303）。定案：階段 2 的回補 SQL 只做扣除①②，不做扣除③，改由 request-time 執法軸⑥ @require_license 擋——這與 provisioning 的 A 方案同一哲學（授予寬鬆、判定嚴格）：多給的能力點在無照模組上打不動任何端點，照上傳後自動對齊。手冊註明「升級後角色可能持有未授權模組的能力點，實際可用性由授權決定」。若決策者要求 SQL 層也扣，開卡前先查 tenant_licenses 解析快取欄位能否直接 jsonb 取模組清單（§8）。
• 執行順序：在 migrate.sh 第三輪、所有 migration（主線＋套件）套完之後——避免 D4 的 id 地雷（seed 尚未 name-based 的舊庫上，先 upsert 再跑 seed 會佔 id）。
• 輸出：RAISE NOTICE 印「能力點新增 K 筆／root 補 X 筆／租戶角色回補 R 個角色 Y 筆」，migrate.sh 原樣轉印。

④ migrate.sh 第三輪

APPLY=1 時在第二輪之後：psql --single-transaction -f packages/_capabilities.sql → -f init/migrate-capability-grants.sql；dry-run 只印「將 upsert N 筆能力點宣告」（N＝檔內 VALUES 列數）。兩支都不登記 schema_migrations。

5.3 階段 3：選單守衛＋24 支套件 SQL 冪等核對

① 守衛 test/test_package_ui_routes_have_route_capabilities.py

• 掃描範圍：~/Projects/Jedicogy/module/jedi-python-package/jedi-*/*/migrations/*.sql（本機源碼，CI 以 site-packages 為準：兩者擇一由環境變數決定）＋主專案 scripts/sql/*.sql。
• 規則：每個 INSERT INTO public.ui_routes 語句抽出 name= 字面值（正則抓 WHERE NOT EXISTS (SELECT 1 FROM public.ui_routes WHERE name = '<x>') 或 VALUES 內第 4 欄），同一檔內必須有 route_capabilities INSERT 引用同一 name（FROM public.ui_routes WHERE name = '<x>'）。group-* 節點（pid=0）豁免。
• 突變測試：故意把 cm1423 的 ④ 段刪掉跑一次要紅，還原後綠。
• 另一道 migrate 尾端斷言 SQL（放 migrate-capability-grants.sql 末段）：SELECT count(*) FROM ui_routes u WHERE u.pid<>0 AND NOT EXISTS (SELECT 1 FROM route_capabilities WHERE route_id=u.id) 大於基線白名單數即 RAISE WARNING（不 EXCEPTION：既有基線本來就有 fail-open 的頁，先列出不擋升級；白名單由開卡棒盤點 DEV 現況產出）。

② 每支有頁面的套件 migration 補 ui_routes＋route_capabilities

• 樣板：scripts/sql/2026-08-29-cm1423-security-policy-page.sql 的 ③④ 段；pid 改成 (SELECT id FROM public.ui_routes WHERE name = 'group-system-config') 反查，不寫 47。
• 開卡前盤點哪些套件有頁面（FE 路由 ↔︎ 套件對照），逐套件開新序號檔（如 jedi_asset/003-asset-ui-routes.sql），不改既有 001／002。

③ 24 支套件 SQL 逐支對 DEV 實況 diff、修到冪等

• 方法：對每支 SQL 在 DEV 快照庫（pg_dump 本機 DEV 後 restore 到臨時庫）連跑兩次，第一次可容忍「表已存在」類錯誤並記錄，第二次零錯才過；同時 pg_dump --schema-only 比對套件 SQL 建出的結構 vs DEV 實況（inventory/batch-D.md:836 記 detection 缺 7 條 FK 是已知差）。
• 修法：CREATE TABLE/INDEX/TYPE ... IF NOT EXISTS、DO $$ BEGIN ... EXCEPTION WHEN duplicate_object THEN NULL END $$、ALTER TABLE ... ADD COLUMN IF NOT EXISTS、FK 用 DO $$ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname=...)、資料用 ON CONFLICT／WHERE NOT EXISTS。
• 漂移補正方向：以 DEV 實況（＝02-schema.sql 基線）為準改套件 SQL，不反向改基線（D3）。
• 產出：每支套件 migrations/ 內的修正 commit（jedi repo）＋一份對照表（套件／檔／差異／修法）進 docs/features/FR-093-.../inventory/package-sql-idempotency.md。

④ 併 jedi 1.1.0

走 jedi-package-dev：主專案 pyproject 切 path dependency 開發、驗通後還原 pin；發版等令；1.1.0 wheel 裝上後重跑階段 1 攤平＋stamp gate，第二輪差集應只剩新增的 003 檔。

每列＝一張 Notion 子卡。「動哪些檔」是 runner 開工座標；「驗收條件」是決策者複測清單。

FR-093.1 出貨線接套件 migration — 4 棒

FR-093.2 能力點自動到位 — 3 棒

FR-093.3 選單守衛＋套件 SQL 冪等核對（併 jedi 1.1.0）— 3 棒

共 10 棒（.1 四棒、.2 三棒、.3 三棒）。平行關係：.2a 可與 .1 全程平行；.2b 等 .1a；.3b 等 .1d；.3c 收尾。

全案收口時在一台乾淨機器依序做，任一步不過即退回對應階段：

1. 乾淨機裝新版：install.sh 新裝 → SELECT filename FROM schema_migrations WHERE filename LIKE 'packages/%' 得 24 筆（1.1.0 後含新 ui-routes 檔）；\dT+ compliance.system_status_enum 小寫。
2. 帶舊資料升級：用 v1.19.0 出貨基線建庫、灌一個租戶＋租戶管理員＋幾筆 devices，再 install.sh --upgrade 到本版 → 舊資料完整、packages/% 24 筆、enum 小寫且既有列值跟著變。
3. 租戶管理員登入點新頁面不 403：以升級前就存在的租戶管理員登入，開套件新頁面（如資產清冊），能進、能寫。
4. 選單可見性正確：管理員看得到新頁面選單；只持有基礎角色的使用者看不到；route_capabilities 孤兒 0。
5. schema_migrations 含 packages/ 前綴 24 筆（與 1 同查詢，升級路徑再驗一次），且重跑 migrate.sh 待套 0、能力點 upsert 0 新增、回補 0 筆（冪等）。
6. 守衛：pytest test/test_package_ui_routes_have_route_capabilities.py 綠；build_init_image.sh stamp gate 三張 diff 全空。