# 盤點 ①：授權守門與能力點現況（BE + jedi-iam）

> 2026-10-06 探脈產出，唯讀盤點，供討論稿引用。jedi-iam 路徑以 `~/Projects/Jedicogy/module/jedi-python-package/jedi-iam/jedi_iam/` 為根。

最需要注意的三點：
- **判定層完全沒用到部門範圍。** `user_roles` 有 `org_unit_id` 和 `scope` 兩欄，但判定只比 `tenant_id`。
- **`api/` 下 61 支掛 `jwt_required` 的 route 檔裡，33 支沒有任何能力點守門。** OSCAL SSP 那一整組 13 支都在其中。
- **有兩個讀取端不過濾「有效指派」。** 一是選單明細（`user_service.py:522-529`），二是 JWT 的 `is_admin` claim（`jwt_mw.py:79`）。

## 1. 能力點 schema 與讀取端

ORM model 全部在 jedi-iam 的 `infra/models/`，BE 這邊沒有。

| 表 | 檔:行 | 欄位 |
|---|---|---|
| capabilities | `capability.py:15-27` | id、name(100, UNIQUE)、resource_type(100)、action(50)、description、is_platform(bool) |
| role_capabilities | `role_capability.py:14-23` | role_id + capability_id 複合主鍵，兩邊都是 FK、CASCADE；沒有 pattern／wildcard 欄 |
| route_capabilities | `route_capability.py:18-33` | route_id + capability_id 複合主鍵，另有 requirement(ANY/ALL enum) |
| user_roles | `user_role.py:20-84` | id、user_id、role_id、tenant_id、org_unit_id、starts_at、ends_at(timestamptz)、scope(預設 'tenant')、is_default |
| user_roles 約束 | `user_role.py:26-44` | CHECK tenant_id 或 org_unit_id 至少一個不為空；兩條部分唯一索引：(user,role,tenant,starts_at) WHERE org_unit_id IS NULL，(user,role,org_unit,starts_at) WHERE tenant_id IS NULL |
| roles | `role.py:23-84` | uid、pid、name、enable、is_admin(int)、is_delete、tenant_id；`role.capabilities` 是 association_proxy（`role.py:76-84`） |

`role_capabilities` 的讀取端：

| 用途 | 檔:行 | 有沒有套 `active_user_role_conditions` |
|---|---|---|
| 判定 | jedi-iam `infra/repository/user_role_repo_impl.py:73-101`（`get_active_capability_names`） | 有 |
| 選單可見性 | jedi-iam `infra/repository/ui_route_repo_impl.py:70-141`（子查詢在 :87-103） | 有 |
| 選單明細（每個節點列出持有的 caps） | jedi-iam `app/service/user_service.py:522-529, 547` | **沒有**：直接迭代 `user.roles → role.capabilities`，不過濾效期、停用、租戶 |
| JWT claim `is_admin` | jedi-iam `middleware/jwt_mw.py:79` | **沒有**：`any(role.is_admin == 1 for role in user.roles)`，不看 role_capabilities，但同樣不過濾 |
| 角色 CRUD 寫入 | jedi-iam `domain/service/role_domain_service.py:88-90`（新增）、`:96-117`（先刪光再重建） | 不適用 |
| 角色 CRUD 讀出 | jedi-iam `infra/mapper/role_mapper.py:32`、`app/dto/role.py:55`、`app/service/role_service.py:76,91` | 不適用 |
| BE 角色 CRUD 授權檢查 | `app/auth/service/role_app_service.py:41,49-51`（讀既有角色的 `existing.capabilities` id）、`:54-91`（`_assert_new_capabilities_licensed`，用 `get_capabilities_by_id_list` 取 resource_type） | 不適用 |
| BE 其他 | `core/plugins/evidence_classification.py:140-142`（`viewer_has_capability`）；`common/authz/capability.py` 只是轉接到 jedi-iam 的 shim；DI 接線在 `di_containers/auth/auth_containers.py:57,100,122` | — |

## 2. jedi-iam 判定層

- **`active_user_role_conditions`**：`infra/repository/active_role_conditions.py:19-39`。條件依序是：
  - `UserRole.starts_at <= now()`
  - `UserRole.ends_at IS NULL OR ends_at >= now()`：含等號，`now()` 取 DB 時間，欄位是 timestamptz
  - `Role.enable == 1`
  - `Role.is_delete == 0`
  - 有給 tenant_id 時，再加 `UserRole.tenant_id == tenant_id`
- **`get_active_capability_names` 的查詢形狀**：`user_role_repo_impl.py:81-101`。
  - 從 Capability 依序 join RoleCapability、UserRole、Role，最後 `DISTINCT name`。
  - 查本人時直接用 `UserRole.user_id`，不 join users（為了避開 RLS）；查他人時才 join User 比 uid。
  - **完全沒用 `org_unit_id` 或 `scope`，也沒有子部門繼承。** 只要 context 有 tenant_id，`tenant_id IS NULL` 的部門指派一律被排除。
- **CapabilityGuard**：`authz/capability.py:51-66`。
  - `capability_names_for` 從 `get_user_context().tenant_id` 取租戶。
  - 快取只有單一請求內有效：存在 `flask.g`，key 是 `_authz_capability_names`（:48, :99-106），沒有跨請求快取。
  - super_admin 一律放行：`viewer_has_capability` 在 :115、`require_capability` 在 :135。
  - guard 預設從 DI 取得（:69-77），可用 `set_guard_resolver` 換掉（:85）。

## 3. 守門覆蓋（`api/` 下有 `jwt_required` 的檔，共 61 支）

分組方式是對整支檔 grep 守門字樣。G 組代表「檔內至少一處有守門」，不保證每個方法都有。jedi-iam 自己的 route（例如 role_route）不在 BE 的 `api/` 下，沒算進來。

**G 組：有 require_capability / platform_admin / super_admin / signed_token 等守門，28 支**
- `ai_call_log/ai_call_log_route`
- `cloud_integration/`：`drive_app_credential_verify`、`google_drive_integration`、`google_drive_sync`
- `flow_control/project_route`
- `flow_engine/flow_template_route`
- `module_frame/` 共 15 支：mf_ssp_export、components、control_default、control_objective_default、import、inventory、item、leveraged、party、reference_document、module_frame_route、ssp_resources、system_characteristic、template_import、ssp_import_template
- `notify_config/notify_config_route`
- `oscal/`：`framework/oscal_framework_version`、`module_frame_template_ssp`、`resource_library`
- `project/project_route`
- `support/recent_error_route`
- `system_config/security_policy_route`

**J 組：只有 `jwt_required`，33 支**

| 模組 | 數量 | 檔案 |
|---|---|---|
| oscal（SSP） | 13 | ssp_components、ssp_control_impl_import、ssp_control_implementation、ssp_document_pool、ssp_docx_import、ssp_excel_import、ssp_export、ssp_inventory_items、ssp_leveraged、ssp_party、ssp_resources、ssp_scoped_excel_import、ssp_system_characteristic |
| oscal（framework） | 3 | framework_parse_job、framework_version_edit、oscal_framework_route |
| flow_engine | 5 | flow_engine_route、job_evidence、stage_advance、stage_object、stage_rollback |
| grc（flow_control） | 3 | assessment_plan、job_force_start、job_route |
| grc（project） | 3 | ap_docx_import、ar_import、audit_round |
| grc（project_summary_report） | 2 | project_summary_report_route、project_summary_report_history_route |
| system | 2 | system_config/system_config_route、setup/setup_route（設定精靈，可能是刻意不設守門） |
| 其他 | 2 | ai_quota/ai_quota_route、support/diagnostic_bundle_route |

注意：J 組的 SSP／flow_engine／grc 多數在 service 層有專案成員角色守門（見盤點 ②），「沒掛能力點」不等於「誰登入都能用」，但確實缺了租戶 RBAC 這一層。

## 4. 能力點命名現況（DEV DB）

- 共 123 個能力點，37 種 resource_type，其中 16 個 `is_platform = true`。

| resource 命名 | resource_type 種數 | 能力點筆數 |
|---|---|---|
| 底線 | 4 | 13 |
| 連字號 | 19 | 56 |
| 單字，無分隔 | 14 | 54 |

- 用底線的 4 個 resource_type：`cloud_integration`、`notify_config`、`system_config`、`flow_template`。
- 非 CRUD 的動詞：`export` ×2（feedback、project）、`assign` ×1（project）、`approve` ×1（project）。
- 沒掛任何 route 的孤兒能力點有 9 個：`cloud_integration.update`、`feedback.export`、`system_config.create/delete/update`、`workflow.create/delete/read/update`。
- `system_config` 只有 create/delete/update，沒有 read；而對應的 `system_config_route` 剛好落在第 3 節的 J 組。

## 5. 預設角色 seed

- **出貨基線**：`scripts/init/04-seed-core.sql`。只有 1 個角色：`Administrator`，id=2、tenant_id=1、`is_admin = 1`（:62）。從 :272 起是 123 列 role_capabilities，用名稱反查 id，等於全部能力點都配給它。
- **產生器**：`scripts/init/gen_capability_seed.sql`，由 `gen_seed_sql.sh:86` 呼叫，結尾在 :292-327 有筆數自檢。改用名稱反查的理由寫在 `scripts/init/README.md:57-66`（CM-1757）。
- **新租戶**：jedi-iam `app/service/tenant_provisioning_service.py:49` 會建一個 `"System Manager"` 角色，配「能力點全集扣掉排除清單」，並在 :149 設成 `is_admin = 1`。
- **既有租戶回補**：`scripts/init/migrate-capability-grants.sql` 是模板，build 時產出 `scripts/sql/packages/_capability_grants.sql`。
- **「新增能力點後幫舊角色補配」的 migration 範例**：`scripts/sql/2026-09-25-fr114-module-frame-read-capability-backfill.sql`。
- DEV 現況：活著的角色有 14 個，`is_admin = 1` 的有 9 個。

## 6. 角色匯出／匯入

**目前沒有。** 角色端點只有 `/roles/menu`、`/roles`、`/role`、`/role/<uid>`、`/role/status/<uid>` 5 個，定義在 jedi-iam `api/routing.py:107-111`，全部是 CRUD 或狀態切換。