45 lines
2.1 KiB
Markdown
45 lines
2.1 KiB
Markdown
# member-platform 架構總覽（Keycloak 版）
|
||
|
||
## 核心模型
|
||
- 業務層：`companies -> sites`
|
||
- 身分層：`users <-> sites`（多對多，透過 `user_sites`）
|
||
- 能力層：`systems -> roles`
|
||
- 授權層：`sites <-> roles`（多對多，透過 `site_roles`）
|
||
|
||
## 權限模型（已定版）
|
||
- `permission` 正式改名為 `role`。
|
||
- `role` 僅能指派給 `site`，不可直接指派給 `user`。
|
||
- `system` / `role` 以 Keycloak 為唯一建立來源；member 後台只做同步顯示與關聯。
|
||
- `user` 的有效角色由以下關聯推導：
|
||
- `user_sites`（使用者屬於哪些 site）
|
||
- `site_roles`（site 擁有哪些 role）
|
||
- 不再使用舊的 `permission_groups` 主流程。
|
||
|
||
## Key 規則
|
||
- `system_key`: `SYyyyyMMddX####`
|
||
- `company_key`: `CPyyyyMMddX####`
|
||
- `site_key`: `STyyyyMMddX####`
|
||
- `role_key`: `RLyyyyMMddX####`
|
||
|
||
## Keycloak 同步策略
|
||
- Keycloak 為唯一 IdP。
|
||
- 群組階層：`Company Group -> Site SubGroup`。
|
||
- 系統角色：以 Keycloak client role 表示，對應 DB `roles`。
|
||
- `site_roles` 代表某 Site 擁有的 Keycloak role 集合。
|
||
- 同步策略改為手動觸發：不在列表讀取 (`R`) 時自動同步。
|
||
- 補齊策略：僅在手動同步按鈕（`POST /admin/sync/from-provider`）或 CUD 流程時同步。
|
||
- 站台角色指派（`PUT /admin/sites/{site_key}/roles`、`PUT /admin/roles/{role_key}/sites`）會即時同步到 Keycloak Group Role Mapping。
|
||
- 使用者加入 Site 時，透過同步邏輯使其在 IdP 端取得對應角色能力。
|
||
- 讀取效能：後端採用 memory cache（後續可換 Redis），`GET` 先讀快取；`POST/PUT/PATCH/DELETE` 成功後自動失效快取。
|
||
- 快取後端可由 `.env` 切換：`CACHE_BACKEND=memory|redis`（無需改程式）。
|
||
|
||
## 後台安全線
|
||
- `/admin/*` 必須 Bearer token。
|
||
- 後端以 Keycloak realm role 判定是否可進站與後台。
|
||
- 未具備 `MEMBER_REQUIRED_REALM_ROLES` 的帳號，`/me` 與 `/admin/*` 皆拒絕。
|
||
- 未具備 `ADMIN_REQUIRED_REALM_ROLES` 的帳號，`/admin/*` 拒絕。
|
||
|
||
## API 白名單
|
||
- 保留 `api_clients` 做系統對系統呼叫控管。
|
||
- 管理後台登入控管與 API client 白名單是兩條獨立安全線。
|