feat(sync): keycloak as source-of-truth with auto catalog sync and token refresh

docs/ARCHITECTURE.md

@@ -9,6 +9,7 @@
 ## 權限模型（已定版）
 - `permission` 正式改名為 `role`。
 - `role` 僅能指派給 `site`，不可直接指派給 `user`。
+- `system` / `role` 以 Keycloak 為唯一建立來源；member 後台只做同步顯示與關聯。
 - `user` 的有效角色由以下關聯推導：
   - `user_sites`（使用者屬於哪些 site）
   - `site_roles`（site 擁有哪些 role）
@@ -25,6 +26,7 @@
 - 群組階層：`Company Group -> Site SubGroup`。
 - 系統角色：以 Keycloak client role 表示，對應 DB `roles`。
 - `site_roles` 代表某 Site 擁有的 Keycloak role 集合。
+- 補齊策略：若 Keycloak 有、DB 沒有，後台同步流程會自動 upsert 到 DB。
 - 使用者加入 Site 時，透過同步邏輯使其在 IdP 端取得對應角色能力。
 
 ## 後台安全線

docs/BACKEND_TASKPLAN.md

@@ -1,7 +1,7 @@
 # Backend TaskPlan
 
 ## 待辦
-- [ ] Keycloak 同步器改版：Company/Site group 同步、System client role 同步、Site 角色套用同步。
+- [ ] Keycloak 同步器優化：Company/Site group 同步、System client role 同步、Site 角色套用同步（含效能與重複同步抑制）。
 - [ ] 補齊 pytest API 測試（CRUD、關聯、同步、刪除、錯誤碼）。
 - [ ] 補一支「一鍵重建 schema」腳本（串 `init_schema.sql`）。
 
@@ -18,3 +18,6 @@
 - [x] 保留 `api_clients` 白名單管理 API。
 - [x] Keycloak OIDC 登入主流程。
 - [x] `/admin/*` Bearer + admin 群組白名單安全線。
+- [x] 公司/站台 CRUD 同步 Keycloak Group（create/update/delete）。
+- [x] Keycloak -> DB 補齊同步（公司/站台/系統/角色/使用者）。
+- [x] 系統改為 Keycloak 唯一來源（後台停用 system CRUD）。

docs/FRONTEND_HANDOFF.md

@@ -14,11 +14,12 @@
   - 此站台綁定的 `roles`
   - 此站台包含的 `users`
 
-3. 系統管理（CRUD）
+3. 系統管理（唯讀 + 同步）
 - 欄位：`system_key`, `name`, `idp_client_id`, `status`
 - 系統詳情需顯示底下 `roles` 列表
+- 建立/修改/刪除在 Keycloak 處理，member 後台提供「同步 Keycloak」按鈕
 
-4. 角色管理（CRUD）
+4. 角色管理（DB 關聯為主）
 - 欄位：`role_key`, `system_key`, `name`, `description`, `idp_role_name`, `status`
 - 關聯操作：指派到 Site（新增/刪除 `site_roles`）
 

docs/FRONTEND_TASKPLAN.md

@@ -12,7 +12,7 @@
 - [x] 後台導覽改版：`公司 / 站台 / 系統 / 角色 / 會員 / API Clients`。
 - [x] 公司頁：CRUD + 公司底下站台列表。
 - [x] 站台頁：CRUD + 站台角色指派 + 站台會員列表。
-- [x] 系統頁：CRUD + 系統底下角色列表。
+- [x] 系統頁：改為 Keycloak 唯一來源（唯讀 + 手動同步按鈕 + 角色列表）。
 - [x] 角色頁：CRUD + 角色綁定站台列表。
 - [x] 會員頁：CRUD + User 綁 Site + 顯示推導角色 + 重設密碼。
 - [x] 刪除流程補齊（公司/站台/系統/角色/會員/API client）。

docs/LOCAL_DEV_RUNBOOK.md

@@ -37,13 +37,15 @@ npm run dev
 2. 前端按「前往 Keycloak 登入」應可成功導轉與回跳。
 3. `GET /me` 登入後應有資料。
 4. 非 admin 群組帳號打 `/admin/*` 應為 403。
+5. `POST /admin/sync/from-keycloak?force=true` 可手動觸發全量補齊同步。
 
 ## 6) 新模型驗收路徑
 1. 新增 Company、Site。
-2. 新增 System、Role。
-3. 對 Site 指派 Role。
-4. 新增 User，加入 Site。
-5. 驗證 User 的角色是由 Site 推導，不是 direct assign。
+2. 在 Keycloak 建立 System（Client）與 Role（Client Role）。
+3. 在後台按「同步 Keycloak」，確認 DB 補齊 System/Role。
+4. 對 Site 指派 Role。
+5. 新增 User，加入 Site。
+6. 驗證 User 的角色是由 Site 推導，不是 direct assign。
 
 ## 7) API 白名單驗收
 1. 建立 `api_client`。

docs/index.md

@@ -21,6 +21,7 @@
 - 權限定版：`Role` 只能指派給 `Site`（透過 `site_roles`）。
 - 成員授權定版：`User` 不直接綁 `Role`，僅透過 `user_sites` 取得 Site 角色。
 - IdP 定版：Keycloak 為唯一 IdP。
+- 系統定版：`System`/`Role` 由 Keycloak 管理，member 後台僅同步與顯示。
 - API 白名單：保留 `api_clients`。
 - 後端：新 schema 與 admin/internal API 已切到 role-site 模型。
 - 前端：管理頁已切到新模型（公司/站台/系統/角色/會員/API Clients）。