docs: rebuild architecture and taskplans for role-site model

docs/ARCHITECTURE.md

@@ -1,26 +1,37 @@
-# member.ose.tw 架構總覽
+# member.ose.tw 架構總覽（Keycloak 版）
 
 ## 核心模型
-- 業務層：`companies -> sites -> users`
-- 功能層：`systems -> modules`
-- 權限層：`permission_groups`（群組中心）
+- 業務層：`companies -> sites`
+- 身分層：`users <-> sites`（多對多，透過 `user_sites`）
+- 能力層：`systems -> roles`
+- 授權層：`sites <-> roles`（多對多，透過 `site_roles`）
 
-## 權限規則
-- `scope_type` 固定 `site`
-- `action` 僅 `view` / `edit`（可同時存在）
-- 權限透過群組下發給會員，不走細粒度 direct permission 主流程
+## 權限模型（已定版）
+- `permission` 正式改名為 `role`。
+- `role` 僅能指派給 `site`，不可直接指派給 `user`。
+- `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 集合。
+- 使用者加入 Site 時，透過同步邏輯使其在 IdP 端取得對應角色能力。
 
 ## 後台安全線
-- 所有 `/admin/*` 需 Bearer token
-- 後端僅依 `ADMIN_REQUIRED_GROUPS` 判定可否進後台
-- 不在群組就算有網址、有 IdP 帳號也會 403
+- `/admin/*` 必須 Bearer token。
+- 後端以 admin 群組白名單判定是否可進後台。
+- 有 Keycloak 帳號但不在 admin 白名單者，後台 API 一律拒絕。
 
-## 會員資料與 IdP 對齊（Keycloak 優先）
-- `username`：登入帳號（可編輯，可同步）
-- `display_name`：顯示名稱（可編輯，可同步到 IdP profile）
-- `user_sub`：由 IdP 主體識別值回寫
-- `idp_user_id`：保存 IdP 端 user id（字串），供更新/密碼重設
-
-## 密碼流程
-- 目前：後台可觸發重設密碼（產生臨時密碼）
-- SMTP 開通後：可再補「發送密碼設定/重設通知」自動化
+## API 白名單
+- 保留 `api_clients` 做系統對系統呼叫控管。
+- 管理後台登入控管與 API client 白名單是兩條獨立安全線。