FR-065.0 DB 初始化基線——盤點報告（CM-1207 盤點棒）

• 日期：2026-08-15
• 性質：唯讀盤點。本文件是「從零建庫需要什麼」的完整清單與方案草案，不含任何已執行的 DB 異動。
• 資料源：DEV DB 192.168.50.188:25432/guidant_ai_dev（帳號 cmmgr，全程唯讀：pg_dump --schema-only、SELECT、catalog 查詢）＋ BE repo scripts/sql/ ＋ jedi-auth 套件源碼。
• 母案：CM-1189（FR-065 落地版 Installer）；本卡 CM-1207。
• 路徑註記：派工單寫 docs/features/FR-065-2608-installer/，但 docs/features/README.md 登記名為 FR-065-2608-onprem-installer，依 FR 編號鐵則採 README 登記名。

1.1 總量（DEV 實況，2026-08-15 pg_dump 為準）

分區維護：maintain_log_partitions() 負責 api_logs / system_logs 月分區滾動；init 時需建立母表＋當月分區＋default 分區（DEV 現況有 2026_05~2026_08 各月子表——歷史月份子表不屬基線，init 只需母表＋default＋當期）。

1.2 版位追蹤三張表現況

1.3 對照 scripts/sql/ migration 串

• scripts/sql/ 有 224 支 .sql ＋ manifest.tsv（CM-1086 建，四欄：filename/phase/envs/note）。
• manifest 分類：pre-baseline 83 筆（永不套，2026-05-28 baseline 之前的歷史）＋ active 138 筆。active 中 127 筆 envs=*、11 筆是環境限定（dev/stg/poc 專屬——如 DEV cleanup、STG cutover 類，不屬產品基線）。
• DEV schema_migrations 登記 138 筆與 manifest active 段一致（含 __baseline_pre_2026-05-28__ marker 與 2 支無日期前綴的 oscal-v2 檔）。
• 結論：基線收斂的「真相」取 DEV pg_dump 實況；manifest.tsv 已提供哪些 migration 屬環境專屬（不進基線）的判準，收斂時逐支核對 envs 欄即可。
• 隨附資產：scripts/sql/view/vw_user_job_queue.sql、scripts/sql/store_procedure/sp_get_user_task_queue.sql（view/SP 的 canonical 源，dump 內已含定義）、scripts/sql/seeds/bpmn/ 4 支內建 BPMN（builtin-full-audit / builtin-full-audit-with-review / builtin-internal-check / builtin-self-assessment，對應 flow_templates 內建流程）。

2.1 掃描結果：目前零缺口

用 has_table_privilege / has_sequence_privilege / has_function_privilege 對 cm_app 全量掃描（5 schema、186 表、156 sequence、6 view、全部 function）：

• 表缺 SELECT/INSERT/UPDATE/DELETE 任一者：0 張
• Sequence 缺 USAGE：0 支
• View 缺 SELECT：0 支；Function 缺 EXECUTE：0 支

「歷史 migration 常漏 GRANT」的坑在 DEV 已被兩層機制補平：

1. ALTER DEFAULT PRIVILEGES：五個 schema 都設了（grantor=cmmgr）——tables SELECT,INSERT,UPDATE,DELETE、sequences USAGE,SELECT,UPDATE、functions EXECUTE 自動授予 cm_app。之後由 cmmgr 建的新物件天生有權限。
2. Event trigger trg_auto_grant_cm_app（auto_grant_cm_app_on_new_schema()）：CREATE SCHEMA 時自動 GRANT USAGE ＋補設該 schema 的 default privileges。

→ 基線 init 的正確做法不是逐表 GRANT 400 行，而是複製這套機制：建 schema 後先設 default privileges，再建物件；event trigger 一併帶入。逐表 GRANT 僅作為驗收檢查（掃描 SQL 可直接沿用本次盤點語句）。

2.2 DB 角色現況與 RLS 關係

RLS 運作方式：107 條 policy 全部掛在 public（即對所有非 BYPASSRLS 角色生效），判斷條件不是 DB role 而是 session GUC——app.user_id、app.allowed_tenant_paths、app.is_super_admin 等，由 session_scope() 每次查詢前注入（helper：app_tenant_allowed_for_session() 一族）。因此：

• cm_app 的資料隔離完全靠「應用層注入 GUC ＋ policy」實現，不依賴 per-tenant DB 帳號；
• cmmgr 因 BYPASSRLS 可做系統層寫入（seed、migration）；
• init 對 RLS 的責任＝把 29 張表的 ENABLE ROW LEVEL SECURITY ＋ 107 條 policy ＋ app_* helper functions 原樣建齊（皆已含在 pg_dump 內）。
• 另注意 pg_db_role_setting 為空——沒有任何 DB/role 層級的 GUC 預設值，不需搬。

分類定義：①產品必備＝新客戶空庫必 seed；②環境相依＝installer 參數化或安裝後由管理介面設定；③DEV 殘留＝不隨產品出貨。業務資料表（projects / ssp / 評鑑 / survey 答題 / job 執行 / log 類）在新庫本來就該是空的，不逐一列出——DEV 裡它們有資料屬開發測試產物，全數不出貨。

3.1 ①產品必備（字典/系統定義類，值不因客戶而異）

3.2 ②環境相依（installer 參數化，或出廠帶「未啟用」空殼）

3.3 ③DEV 殘留（不出貨）

• 測試租戶整族：tenants 102(Billows Tech)/131(歐洲航空)/152/153/158(JEDI) 及其 org_units、roles、users（blsadmin/blsit/e2e_* 等 38 個帳號）、module_frames 154 筆、flow_templates 9 筆、surveys、devices、labels 泰半、issues/feedback_issues、drive_* 整族、totp_secrets、tenant_drive_integrations。
• 業務資料：projects 210、job_executions 1 萬+、workflow_executions、SSP/AP/AR/POA&M 全族、question_answers、upload_files 2668、login_tokens/login_logs、api_logs/system_logs 分區資料。
• 明確垃圾表：survey.question_answers_dedup_backup_20260428、config.detection_tool_profiles_deprecated_20260803、public.system_logs_old——基線 schema 不帶這三張（連結構都不帶）。
• public.system_configs 之 NOTIFY_CONFIG（tenant 102 的 Discord/Telegram webhook，內含真實 secret）——不出貨。

3.4 ⚠️ 待裁決清單（拿不準，留給決策者）

4.1 DB 帳號（cmmgr / cm_app）

• 建立紀錄不在 repo 內：scripts/sql/ 與 docs 全量 grep 無 CREATE ROLE cmmgr/cm_app——推測（標註：推測）是當年 DB server 手動建立，屬 cluster-level 操作本來就不進單庫 migration。→ init 機制必須自己補上這塊（首次在客戶主機建 cluster 帳號）。
• 現況屬性見 §2.2。關鍵設計事實：cmmgr=superuser+BYPASSRLS 的管理帳號、cm_app=受 RLS 的應用帳號，兩帳號同密碼是 DEV 慣例，出貨不應沿用（installer 應分別產生）。
• RLS 不依賴帳號屬性以外的東西：只要應用連線帳號非 BYPASSRLS/superuser，policy 就生效；GUC 注入由應用層負責。
• ⚠️ 出貨層面注意：cmmgr 目前是 SUPERUSER——若客戶端 DB 是客戶自管（RDS 類），SUPERUSER 拿不到。基線最低需求其實是「DB owner + CREATEROLE + BYPASSRLS」，init 設計時建議降規（列入 §5 考量，實作棒驗證）。

4.2 應用層帳號（users 表）

• 密碼儲存：bcrypt $2b$12$（cost 12），per-user salt 存 users.salt 欄（bcrypt.gensalt()），hash 60 字元存 users.password。DEV 39 個帳號全部同一格式，無 legacy 雜湊。實作在 jedi-auth user_domain_service.add_user()。
• DEV 超管現況：admin（tenant 1，is_super_admin=true，DEV id=16）＋blsadmin（tenant 102 的租戶超管）。admin 的建立同樣查無 seed SQL（推測 legacy 手動/早期工具建立）；後續由 2026-06-29-b2-admin-root-tenant.sql 把它掛進 root tenant（users.tenant_id→1 ＋ user_tenants ＋ user_org_units 三筆，B-2 模型）。init 建初始 admin 時這三件事要一次做齊，否則重演「super admin 寫入 tenant_id=NULL 孤兒」bug。
• is_super_admin 語意：RLS policy 以 GUC app.is_super_admin='t' 放行全庫，值由登入時從 users.is_super_admin 帶出。

4.3 首登改密／密碼治理（機制已存在，init 可直接復用）

jedi-auth 已內建完整機制，init 不必新造：

• FIRST_REGISTER 變更請求：add_user() 流程會自動產 12 碼複雜密碼（generate_complex_password(12)）＋建立 user_change_password_request（type=FIRST_REGISTER，7 天效期）＋寄密碼信。登入時有 pending request 會被導去改密頁；change_password_by_request() 走密碼政策驗證（≥12 碼+大小寫+數字，CM-683）。
• 密碼過期：RUNTIME_CONFIG.CHANGE_PASSWORD_THRESHOLD_DAYS（預設 90）+ type=PASSWORD_EXPIRE 請求。
• MFA：RUNTIME_CONFIG.MFA_REQUIRED + totp_secrets 表。
• → 初始 admin 的「隨機產生＋強制首登改密」拼圖現成：init 只需以 bcrypt 正確格式寫入 users＋一筆 FIRST_REGISTER change request（效期建議放寬），或最簡單——密碼由 installer 產生後印給安裝者、同時 stamp 一筆過期的 threshold 逼首登改密。細節屬實作棒設計。

5.0 共同前提（不管選哪案都成立）

• 基線真相=DEV pg_dump，不是 224 支 migration 重放。歷史串重放不可行：早期檔互相覆蓋、部分含 DEV 專屬資料修補、環境限定檔混雜。
• 權限不逐表 GRANT：按 §2.1，建 schema →設 default privileges →建物件的順序天生全對，再帶 event trigger 保未來。
• 層次切分：cluster 層（roles、database、extension）與 database 層（schema/物件/seed）必須分開——前者需要連 postgres 庫的權限，後者連目標庫。
• 冪等性：所有 seed 用自然鍵 ON CONFLICT DO NOTHING / INSERT ... WHERE NOT EXISTS；schema 段以「schema_migrations 有無 baseline marker」判斷跳過整段。root tenant/org id=1 硬約定需在空庫 seed 時顯式指定 id 並 setval sequence。
• 收尾 stamp：init 完成時往 schema_migrations 登記（建議登記一筆 __init_baseline_v<版號>__ marker ＋ 把已收斂的 active migration 檔名全數補登），讓日後增量 migration 與三環境 diff 工具無縫接軌；schema_version 補基線版號。這與既有 sql-migration 慣例（檔頭 Date、--single-transaction、cmmgr 執行）完全相容——基線之後的新 migration 照舊制走，不受影響。

5.1 方案 A：單一 init.sql（大一統檔）

pg_dump schema 段＋seed 段＋stamp 段串成一支，installer 用 psql --single-transaction -v ON_ERROR_STOP=1 一發套完。

• ✅ 最簡單、單一交易原子性、與現行 migration 套法零學習成本。
• ❌ 3 萬行大檔難維護難 review；參數注入（admin 密碼、storage 座標）得靠 psql -v 變數穿插在巨檔裡，易錯；cluster 層（CREATE ROLE/DATABASE 不能在交易內、要連不同庫）根本塞不進同一支——實務上一定會裂成「殼腳本＋大 SQL」，那不如直接選 B。

5.2 方案 B：分段腳本組（建議傾向）★

scripts/init/
  00-cluster.sql        # CREATE ROLE cmmgr(降規版)/cm_app/cm_app_group、CREATE DATABASE（連 postgres 庫，殼腳本執行）
  01-extensions.sql     # uuid-ossp、pg_trgm
  02-schema.sql         # 由 pg_dump --schema-only 產出後整理（去 DEV 殘留表、去歷史月分區）
  03-grants.sql         # default privileges ×5 schema + event trigger +（驗收用逐項掃描）
  04-seed-core.sql      # §3.1 字典/權限/選單/root tenant+org/內建流程範本
  05-seed-catalog.sql   # D1~D4 裁決後的框架/profile 資產（可能改走匯入流程，見下）
  06-admin.sql          # 初始 admin（bcrypt hash 由外部算好以 -v 傳入）+ B-2 三件套
  99-stamp.sql          # schema_migrations baseline marker + schema_version
  init.sh               # 依序執行、參數注入（env vars）、冪等判斷、失敗即停

• ✅ 每段可獨立 review/重跑；參數注入面窄（只有 00/04/06 吃參數）；cluster/database 層天然分離；與 manifest.tsv 的維護思路一致；基線升版時只 regenerate 02/03，seed 段不動。
• ❌ 段間非單一交易（02~99 可各自包交易，但整體失敗需 DROP DATABASE 重來——init 場景可接受，殼腳本做好「失敗即整庫重建」語意即可）。
• 觸發者：installer 觸發（呼叫 init.sh），理由見 5.3。

5.3 方案 C：entrypoint 自動 init（容器啟動偵測空庫自動建）

服務容器 entrypoint 起 binary 前檢測 DB，空庫就跑 init。

• ✅ 客戶體驗最滑：docker run 即全好。
• ❌ 服務容器必須持有 cmmgr 級憑證——違反最小權限（runtime 只該有 cm_app）；FR-063 產物是 Nuitka binary，entrypoint 塞 psql/初始化工具鏈會撐大 image；空庫誤判（DB 連錯台）時風險是「在錯的庫建整套 schema」。
• 折衷變體：獨立 init job 容器（同 image family 另一個 one-shot container，或 installer 內嵌 psql client），只有 init 當下拿 superuser 憑證，跑完即棄。若未來要「升級也自動套 migration」，這個 job 容器形態可沿用。

5.4 取捨建議

B（installer 觸發的分段腳本）為主，C 的 init-job 容器作為執行載體：installer 負責產參數（兩組 DB 密碼、admin 初始密碼）→ 起 one-shot init 容器（或直接在主機跑 psql）執行 init.sh → 成功後才起服務容器（只給 cm_app 憑證）。A 不建議單獨採用。

D1 框架資產的特別註記：若裁決結果是「出廠帶 OSCAL JSON、首次啟動匯入」，則 05-seed-catalog.sql 整段換成應用層匯入指令（既有框架匯入 pipeline），DB init 只管空殼——這會顯著縮小 seed dump 的維護面，但拉長首次安裝時間且依賴應用已能啟動。兩路成本留給實作棒對照裁決結果細算。

5.5 參數注入接口（留給 FR-065 installer 的契約草案）