# member.ose.tw 架構總覽（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 白名單是兩條獨立安全線。