存取管理：設計定案

狀態：設計定案（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。前兩段就是角色矩陣的兩層分組，不另建群組表。

粒度規則：

情境判準（2026-10-06 A.1 合併定案）：

• 通則 A：在任務／專案情境裡做的事，看任務／專案的權限。 功能模組的能力點只管該模組自己的管理頁。判準是使用者在哪個頁面按的，不是程式住在哪個套件。授權照與能力點是兩層，模組加值包硬規則管的是能力點，不影響此通則。例：任務頁開始掃描＝grc.job.update（非 detection）；任務頁填問卷＝grc.job.update（非 survey）；專案頁建雲端資料夾＝grc.project.update。 例外：任務產出物結案後視為證據——已完成問卷的內容、答案、歷史、討論與檢測工具執行紀錄，持 grc.job-evidence.read 也能讀（與證據檔同一顆）；未結案問卷仍只認 grc.job.read，只持證據權限的人回 404。寫入不受影響。
• 通則 B：挑選用的下拉／名單，看呼叫頁面的權限，被挑模組的 read 只管它自己的管理頁。 例：建專案選流程範本＝grc.project.create 放行；專案／SSP 頁挑設備、資訊系統＝該頁權限；挑人挑部門下拉豁免。判準：回的是「挑選用的名單」還是「那個東西的內容本體」——後者走通則 C。
• 通則 C：一支 API 服務多種資源時，先解析資源歸屬，再檢查對應的單一權限；不開「擇一放行」。 例：流程定義端點先查 BPMN 屬專案或資源庫。資源域守門放 service 層（與 6.3 一致）。

原廠層（is_platform）端點一律兩道都過：平台管理員判定保留，再加能力點檢查。

模組判準：客戶會不會把這群功能當一組來授權。模組不是 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 合併，2026-10-06）：

已裁結果：information-system 歸 asset；storage-config 歸 system；ai-quota 拆為 ai.quota 與 platform.ai-quota-ceiling；ai-dashboard 獨立成 ai 模組。

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（FE config/router/index.js:93-122），舊網址導向新頁；/auth/user-manage 帳號管理頁保留、瘦身。/auth/user-form-mtrbac 是管理員編輯帳號的表單（UserMTRBACForm.vue，基本資料＋角色），只拿掉角色區塊；路由要不要改名由 T-5.5 回寫決策者。定稿畫面：mockup/role-detail-v3.html（角色明細，頂部切換看新增模式）、mockup/roles-and-assignments-v3.html（角色列表、指派頁、新增指派對話框）；同目錄的 access-management.html、access-management-v2.html 不是定稿，不要照著做。

介面用語（FE i18n 規範）：對使用者一律說「權限」、單位「項」，不出現「能力點」「pattern」「capability」；程式碼、API、資料表照舊用 capability。錯誤訊息（error-code.json）同一規則。

沒有的東西（決策者定）：檢查存取不另開頁；部門隔離設定頁不做（D12 不做）；指派沒有範圍欄、沒有部門篩選——部門指派與整公司判定相同，欄位藏掉，API 的 org_unit_id 參數保留、前端不送（一律 scope=tenant）。

角色明細細節：

新增指派對話框：選人（可多選，每人各產生一筆）、角色下拉、期間（永久／指定起訖兩個日期）；右側即時預覽「可見選單變化」——他目前就有的灰、加上這個角色後新增的綠色加號；按「建立指派」。

BE 要補的三件（前端需要、今天沒有）：① POST /ui-routes/visible-by-capabilities：給一組權限名或角色 uid，回可見頁清單；② 角色回應補 is_system、is_template、規則清單（entity 已有，RoleDTO／RoleResponse 沒帶出）；③ 列表每列補展開後權限數與可見頁數。另有一個陷阱要在帳號管理頁瘦身時一起修：update_user（jedi-iam user_service.py:277-288,352）存帳號時把該使用者的指派全刪再照 payload 重建，重建時不帶起訖；管理員改帳號（PUT /user/<uid>）與本人改個人資料（PUT /user-profile/<uid>，user_route.py:246-255 從既有指派重組、同樣漏起訖）都走這條，存一次帳號，指派的到期日就被清成永久。BE 要改成「沒送 user_roles 就不動指派」，帳號頁不再送。

FE hasCap 約 15 支檔的權限名改新名；版本 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.4、T-3.7、T-3.8、T-3.9）

定稿畫面與規則見 6.6。

A.6 頁內按鈕照權限隱藏 — 依賴：A.3、CM-2556（補權限）

2026-10-07 決策者手測後新增。後端守門與側欄遮蔽做完後，頁內寫入類按鈕大多不看權限（117 支有按鈕的頁只有 17 支判斷、用到 19 項），症狀是「按鈕在、按下去 403」。裁示：隱藏不停用（授權唯讀才用停用＋說明）；專案內頁雙層——公司層權限決定按鈕出不出現、專案成員角色維持「輪到誰做」，兩者都過才顯示，不把成員角色換成公司層權限（那是 FR-B）；前端不看 enforce_mode，只記錄的權限照樣隱藏，否則觀察期看不出誰缺權限。架構（決策者 2026-10-07 拍板，不逐顆補）：三層——路由層（每頁一顆進入權限登記在後端 route_capabilities，前端守衛讀後端回的可進名單）、元素層（v-can 指令唯一寫法）、資料層（專案角色／狀態以 v-if 疊加）；真相唯一鏈 route_capabilities → /users/me/capabilities → userStore → 守衛與指令，前端不寫死任何「哪頁要哪顆」。被排除：逐顆補 v-if（無機制擋新裸頁）、前端路由 meta.capability（第二套真相）、內頁跟側欄頁同門檻（新增頁有 read 就進得去）。取捨全文見 docs/analysis/2026-10-07-fr132-a6-frontend-three-layer-authz.md。

架構

真相唯一：後端表 → GET /users/me/capabilities（capabilities、routes、route_gates）→ userStore → 路由守衛與 v-can。routes 與側欄、角色「可見頁面」預覽走同一條可見判定，三者不會不一致。端點守門不通過拋 CapabilityRequiredError，403 帶 data.required／mode，前端錯誤提示與 /403 頁據此說缺哪顆。

被排除的做法：

• 逐顆補 v-if：沒有機制擋新頁不登記，九種判斷寫法繼續並存，守衛掃不出漏網。
• 前端路由 meta.capability 寫死權限名：第二套真相，與後端漂移時沒人察覺，角色「可見頁面」會與實際不符。
• 內頁跟側欄頁同門檻：有檢視權限就進得了新增頁，送出才 403，只是把問題從按鈕搬到頁面。

規範落點：FE CLAUDE.md「權限守門三層」、BE docs/claude/frontend-overview.md §5.4（含新頁登記五步驟）、.claude/rules/security/endpoints.md「前端對應」、FE .claude/rules/security/frontend.md、reviewer 判準 docs/claude/secure-coding-rules.md「前端」。

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