存取管理：設計定案

狀態：設計定案（D1–D12 已拍板）｜日期：2026-10-06｜討論稿（含全部流程圖與現況細節）：discussion.html｜母案：CM-2510（子卡 CM-2511～CM-2541） 前作：FR-048 統一授權守門（common/authz/）、FR-062 License 控管（授權照模組對照）、FR-069 jedi-iam 套件化

2.1 要解決什麼

Guidant AI 的公司層權限是 RBAC（Role-Based Access Control，以角色為單位授權）：管理員建角色、在角色上勾能力點（系統裡「可以做某件事」的最小單位，例如 project.read），再把角色指派給使用者；API 用 require_capability(...) 擋人，判定在 jedi-iam 套件（帳號與權限套件）。骨架都在，但有四個地方沒接上：

另有兩個資安漏洞：選單明細與 JWT（登入後隨每個請求送出的身分憑證）裡的 is_admin claim（憑證內的一個欄位）不過濾已到期、已停用的指派（app/service/user_service.py:522-529,547、middleware/jwt_mw.py:79），會讓過期管理員仍看得到管理頁入口。

資料隔離今天只到租戶：資料庫用 RLS（Row-Level Security，資料庫列層級隔離）擋別租戶的資料，43 張表帶 org_unit_id 但沒有一條讀取 policy（RLS 的過濾規則）看它。要不要讓部門也擋資料，由 D12 做成租戶開關。

2.2 端到端流程

%%{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'}}}%%
flowchart TB
  subgraph DEF["管理員在「存取管理」設定"]
    R1["角色：一組 pattern<br/>例 grc.project.* 、 *.*.read"]
    R2["指派：誰 × 角色 × 範圍（租戶／部門）× 起訖"]
    R3["部門隔離開關（預設關）"]
  end
  subgraph REQ["一次 API 請求"]
    Q1["require_capability('grc.project.update')"] --> Q2{"super_admin？"}
    Q2 -- 是 --> OK["放行"]
    Q2 -- 否 --> Q3["取有效指派<br/>（起訖、啟用、租戶）"]
    Q3 --> Q4["展開 pattern 成能力點集合<br/>（Redis 快取，鍵含清單版本號）"]
    Q4 --> Q5{"集合內有這個能力點？"}
    Q5 -- 否 --> NO["403"]
    Q5 -- 是 --> Q6{"本租戶開了部門隔離？"}
    Q6 -- 否 --> OK
    Q6 -- 是 --> Q7["RLS 只回指派範圍內部門的資料<br/>單筆寫入另比「給這個能力點的指派」涵不涵蓋該筆部門"]
    Q7 --> OK
  end
  R1 --> Q4
  R2 --> Q3
  R3 --> Q6
  CHK["「檢查存取」頁"] -.->|吃同一份展開結果| Q4
  MENU["選單、選單明細、is_admin claim"] -.->|吃同一份展開結果| Q4

一句話：先把能力點清單理乾淨定規則（A.1），再改資料表（A.2）與判定邏輯（A.3），最後同時補守門（A.4）和做新畫面（A.5）。

A.1 → A.2 → A.3 必須照順序；A.4 和 A.5 可以平行。版本落點：版本 1 出 A.1～A.3（客戶無感），版本 2 出 A.4 只記錄版＋A.5，版本 3 出 A.4 真擋。

部門範圍的判法（D4／D12 的落地方式）：範圍套在資料上——一筆掛在部門 X 的指派，在使用者碰的資料列 org_unit_id 落在 X 子樹內時啟用；使用者本人所屬部門（user_org_units）不參與判定。被排除的判法是「拿使用者所屬部門與指派部門互比」：那會讓一個隸屬稽核部、被指派去管財務部專案的人完全用不到那筆指派，且兩種部門混在一起，管理員無法從指派畫面推出結果。

明確不做：拒絕規則（deny）、資料層動作（dataActions）、角色可指派範圍限制（assignableScopes）、IP／時段條件、政策語言、資源實例級統一授權表——理由見討論稿〈已定案事項〉。

jedi-iam 路徑以 jedi-iam/jedi_iam/ 為根，FE 以 compliance-manager-fe/src/ 為根。完整證據見 盤點 ①、盤點 ②、盤點 ③。

6.1 能力點命名與模組

格式：<模組>.<資源>.<動詞>，三段小寫，資源名內部用連字號。例：grc.project.approve、oscal.ssp.export、system.ldap-config.update。前兩段就是角色矩陣的兩層分組，不另建群組表。

粒度規則：

模組判準：客戶會不會把這群功能當一組來授權。模組不是 UI 選單（選單會重排，能力點名是對外契約——授權照、角色 JSON、客戶已勾好的角色都綁著它）；也不照程式住在哪個套件分。

硬規則（模組邊界與授權照加值包對齊）：一個加值包必須整包落在單一模組內，不可橫跨兩個模組；模組可以比加值包大。加值包見 docs/features/FR-062-2608-license-management/design.md 第 6 節：問卷（survey）、檢測三合一（remote-agent-manage、detection-profile、plugin）、雲端整合（cloud_integration）、AI 儀表板（ai-dashboard）。不受授權照管制的基礎設施七項見 common/authz/license.py:107-121。

模組草案（A.1 起點，A.1 合併時定稿）：

A.1 合併時要請決策者裁的歸屬：information-system（grc 或 oscal）、storage-config（evidence 或 system）、ai-quota（platform 或 system）、ai-dashboard 是否獨立成模組（它是賣給租戶的加值包，放「平台（原廠）」名下會誤導）。

6.2 資料模型

capabilities 欄位（改後）：

新表與加欄：

新表照 SQL migration 鐵則：每語句加日期註解、GRANT ... TO cm_app、收尾 INSERT public.schema_migrations。

pattern 語法：三段，每段是名字或 *；* 只能整段，不支援 grc.proj*。合法例：*.*.*、grc.*.*、*.*.read、grc.project.*、grc.project.read。寫入時驗格式，不合法回 400。

seed：scripts/init/04-seed-core.sql 的 123 列 role_capabilities 改為系統管理員一列 *.*.*＋三個範例角色；出貨角色內容以 JSON 檔為來源（scripts/init/ 下新增，A.2 定路徑），seed 由 JSON 產生。

migration 自檢與升級相容：

1. 行為零變化是硬條件：每筆既有 role_capabilities 轉成一筆完整名 pattern；migration 結尾逐角色比對「轉換前能力點集合」與「新表展開後集合」，任一角色不一致整支 rollback（psql --single-transaction -v ON_ERROR_STOP=1）。
2. is_admin 角色轉換規則：租戶內「能力點＝該租戶全集」的 is_admin 角色轉內建系統管理員 *.*.*（設 is_system）；同一租戶有多個時取最早建的那個。其餘 is_admin 角色保留旗標，能力點原樣轉完整名，不升級。三環境實查：DEV、STG、190 的 is_admin 角色皆每租戶有一個配滿者（STG 的 121／101 為版本落後兩個能力點，升級會補）。
3. *.*.* 展開範圍：非 root 租戶展開時扣 is_platform 能力點與 TENANT_ADMIN_EXCLUDED_RESOURCE_TYPES（core/plugins/identity.py:89-95），與新租戶 System Manager 拿到的集合一致（DEV：123 − 16 − 4 ＝ 103）。授權照另由第六軸判，不在展開時扣。
4. 改名的三種消費者：BE require_capability／viewer_has_capability 約 116 處、jedi 套件 11 支檔（jedi_iam 4、jedi_issue 3、jedi_ai_dashboard 2、jedi_detection 1、jedi_system_core 1）、FE hasCap 約 14 支檔——一版內新舊名並存（D11）。
5. 全部是加欄、加表、改資料，沒有刪欄、改型別；帶舊資料升級不會因 schema 失敗，會出事只會是資料改錯，靠第 1 點擋。
6. 所有 migration 落地後回報「出貨基線待重產」（scripts/init/02-schema.sql 與 seed），重產由決策者裁示。

6.3 判定層

判定仍在 jedi-iam CapabilityGuard，require_capability("grc.project.read") 對外介面不變，內部三步：

1. 取有效指派：沿用 active_user_role_conditions，回傳每筆指派的角色 id 與指派部門 path（租戶指派為空）。
2. 展開 pattern：角色 pattern × 能力點清單 → 具體能力點集合。展開只跟「角色有哪些 pattern」與「清單有哪些名字」有關、跟使用者無關，可跨請求快取。
3. 比對：要求的能力點在不在集合內（新舊名皆認，D11）。

快取：

🔴 Redis 讀不到時直接查 DB 展開，不可放行也不可回 403——快取壞掉不能變成權限放寬或全站 403。指派的起訖、啟用每次都查 DB（不進 Redis），所以到期當下就失效，不受快取影響。

部門範圍（範圍套在資料上）：角色不分部門，指派才分部門——角色定義全租戶共用，user_roles.org_unit_id 是這筆指派的範圍。使用者所屬部門（user_org_units）不參與。

第三層的必要性：某人在 A 部門是編輯、在 B 部門是唯讀，RLS 讓他兩邊都看得到，route 層也會因 A 那筆放行 update；只有比對「哪一筆指派給的」才擋得住他改 B 的資料。第三層只掛在 D12 挑選的業務表寫入路徑（6.4）。

同源四條查詢（D8）：

FE 路由守衛 requiresAdmin 吃 claim，claim 修正後自動跟著正確（FE config/router/index.js:1057-1066）。

6.4 部門資料隔離（D12）

%%{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'}}}%%
flowchart TB
  Q["讀一筆業務資料"] --> T{"租戶允許？"}
  T -- 否 --> NO["看不到"]
  T -- 是 --> S{"本租戶開了部門隔離？"}
  S -- 否 --> YES["看得到（與今天相同）"]
  S -- 是 --> B{"can_read_all_orgs 或有有效租戶指派？"}
  B -- 是 --> YES
  B -- 否 --> N{"該列 org_unit_id 為空？"}
  N -- 是 --> YES
  N -- 否 --> P{"該列部門 path 落在<br/>有效部門指派的子樹內？"}
  P -- 是 --> YES
  P -- 否 --> NO

session 變數（照 jedi-common session/database/db.py:205-209 注入 app.allowed_tenant_paths 的做法）：

🔴 app.allowed_org_unit_paths 與既有 app.allowed_org_paths 名字相近、意思不同（指派部門 vs 所屬部門），兩個變數注入處都要寫一行註解寫明差別。

policy 形狀（挑選表的 SELECT／UPDATE／DELETE）：租戶允許 且（本租戶未開隔離 或 app.can_read_all_orgs 為真 或 該列 org_unit_id 為空 或 其 path 落在 app.allowed_org_unit_paths 子樹內）。can_read_all_orgs 是背景流程的系統放行旗標，漏了它，開隔離的租戶裡排程工作會讀不到資料且不報錯。

挑選的表（初估 8～12 張，A.1 定案）：compliance.projects、public.devices、compliance.evidence_batches、compliance.detection_executions、survey.surveys、public.bulletins（要確認與 bulletin_org_units 投遞規則不打架）、compliance.information_systems、compliance.module_frames。不挑工作紀錄、解析任務、子表、設定表；子表靠父表入口間接隔離，A.1 要確認沒有直接列子表的 API 繞過父表。

前置：org_units.path migration 掃一次回填，保證每列有值且格式 /id/…/；path 錯了子樹比對會靜默算錯。

開啟流程：管理員按開啟 → 系統產預覽清單（每位使用者在每張表會少看到幾筆、誰會整張表空掉）→ 確認後寫入開關並記一筆稽核事件。關閉不需預覽。只有系統管理員能動。

6.5 守門補齊

33 支只驗登入的 route（api/ 下，盤點 ① 第 3 節 J 組）：

外部套件自帶的 route（jedi-iam /roles 等、jedi-survey 端點）不在這 33 支內，由 A.1 一併列入對照表、T-4.4 補掛。setup_route 是安裝精靈，安裝當下沒有帳號，A.1 確認是刻意不設守門就登記成豁免清單，不算漏網。SSP、flow_engine、grc 多數在 service 層已有專案成員角色守門，本案補的是租戶 RBAC 這層，兩層並存。

兩階段上線（D5）：

只記錄模式以每個能力點一個旗標控制（新掛的 33 支標成只記錄，既有守門不受影響），不是全域開關——全域開關一開，既有守門也會被放寬。新掛的能力點靠 *.*.* 自動進系統管理員，一般角色由客戶自己勾。

6.6 存取管理前端

一個模組（D1），取代 /auth/role-manage、/auth/role-form、/auth/user-manage、/auth/user-form-mtrbac（FE config/router/index.js:93-122）。

FE hasCap 約 14 支檔的能力點名改新名；版本 2 上線時 BE 已同時接受新舊名，FE 可一次切。

6.7 角色 JSON 匯出匯入

{
  "name": "稽核員",
  "description": "執行稽核、可讀全部專案",
  "is_admin": 0,
  "capabilities": ["grc.*.read", "grc.audit-round.update", "oscal.ssp.read"]
}

依賴鏈：A.1 → A.2 → A.3 → （A.4 ∥ A.5）。每卡粒度為單一 session 一到兩天。jedi-iam 開發期走 poetry path dependency，發版等決策者明示；所有 migration 只套 DEV。

A.1 盤點與規則 — 依賴：無

T-1.1～T-1.5 五份平行；每份產出表欄位固定：route × method → 新三段名 → 現有能力點 → UI 頁，外部套件自帶的 route 一併列入。

A.2 資料地基 — 依賴：A.1

A.3 判定層 — 依賴：A.2

A.4 守門補齊 — 依賴：A.3

A.5 存取管理前端 — 依賴：A.3（T-3.7、T-3.8）

E2E 連動（test repo）：190 E2E 環境的 82 筆角色指派全掛在部門上。開關預設關，這些指派照舊等同全租戶有效，既有回歸不壞；D12 開啟後的行為要另寫測試案，不能拿既有案子打開開關硬跑。E2E 屬母案收口動作，arc 完成後到 test repo 統一補。

release note 要寫的行為變更：

開始時間由決策者與 PM 討論後定；FR-132 只替它預留 capabilities.assignable_scopes 的 project 值。

要做什麼：把專案成員角色（manager／reviewer／auditor／viewer）收進同一套「誰 × 角色 × 範圍 × 時效」，範圍多一層 project；專案內按鈕改由能力點判定，成員角色變成「一組 pattern 的預設角色」。至少要等 A.1 定出能力點樹，FR-B 的按鈕對照表才寫得出來。

已知難處：硬寫角色判斷約 70 處，橫跨主專案與 6 個 jedi 套件（盤點 ② 第 2 節）；五張參與者表同形（第 1 節）；control → group → project 回退規則與只認專案層的精確判法不可互相冒充（participant_role_service.py:34-85、common/authz/project.py:28-90）；流程綁角色寫在 BPMN XML 的 main_role，DEV 有 1150 筆進行中實例各帶一份範本 XML 快照（盤點 ② 第 3、5 節）——翻譯 main_role 要連實例 XML 一起改，或在 _resolve_main_roles（app/flow_engine/service/stage_advance_service.py:584-591）做讀取時轉換。

• 討論稿：discussion.md
• 盤點：inventory/01-authz-capabilities.md、inventory/02-project-roles-and-flow.md、inventory/03-frontend.md
• 授權守門決策表：common/authz/__init__.py
• 統一授權守門設計（FR-048）：docs/analysis/2026-07-07-unified-auth-guard-design.md
• 權限與選單系統設計說明書：docs/system-design/permission/Permission-System-權限與選單系統設計說明書.md
• license 第六軸與基礎設施豁免：common/authz/license.py
• 授權照基礎包／加值包：docs/features/FR-062-2608-license-management/design.md 第 6 節
• 新租戶排除清單：core/plugins/identity.py:89-95
• SQL migration 規範：docs/claude/sql-migration-conventions.md、sql-migration skill