feat(idp): add keycloak-first support with authentik fallback

docs/ARCHITECTURE.md

@@ -13,13 +13,13 @@
 ## 後台安全線
 - 所有 `/admin/*` 需 Bearer token
 - 後端僅依 `ADMIN_REQUIRED_GROUPS` 判定可否進後台
-- 不在群組就算有網址、有 Authentik 帳號也會 403
+- 不在群組就算有網址、有 IdP 帳號也會 403
 
-## 會員資料與 Authentik 對齊
+## 會員資料與 IdP 對齊（Keycloak 優先）
 - `username`：登入帳號（可編輯，可同步）
-- `display_name`：顯示名稱（可編輯，可同步到 Authentik `name`）
-- `user_sub`：由 Authentik UID 回寫
-- `idp_user_id`：保留 Authentik user id，供更新/密碼重設
+- `display_name`：顯示名稱（可編輯，可同步到 IdP profile）
+- `user_sub`：由 IdP 主體識別值回寫
+- `idp_user_id`：保存 IdP 端 user id（字串），供更新/密碼重設
 
 ## 密碼流程
 - 目前：後台可觸發重設密碼（產生臨時密碼）

docs/DB_SCHEMA.md

@@ -8,7 +8,7 @@
 ## 主要表
 - `users`
   - `user_sub` UNIQUE
-  - `idp_user_id` INTEGER
+  - `idp_user_id` VARCHAR(128)
   - `username` UNIQUE
   - `email` UNIQUE
   - `display_name`
@@ -27,10 +27,10 @@
 - `scope_type='site'`
 - `action in ('view','edit')`
 
-## 會員與 Authentik 對齊
-- `users.user_sub` 對應 Authentik `uid`
-- `users.username` 對應 Authentik `username`
-- `users.display_name` 對應 Authentik `name`
+## 會員與 IdP 對齊（Keycloak 優先）
+- `users.user_sub` 對應 IdP 主體識別
+- `users.username` 對應 IdP `username`
+- `users.display_name` 對應 IdP 顯示名稱
 
 ## 快速檢查 SQL
 ```sql

docs/INTERNAL_API_HANDOFF.md

@@ -141,7 +141,7 @@ Response:
 {
   "id": "uuid",
   "user_sub": "authentik-uid",
-  "idp_user_id": 123,
+  "idp_user_id": "idp-user-id-or-uuid",
   "username": "chris",
   "email": "chris@ose.tw",
   "display_name": "Chris",
@@ -166,7 +166,8 @@ Response:
 }
 ```
 
-### POST `/internal/authentik/users/ensure`
+### POST `/internal/idp/users/ensure`
+（相容路徑：`/internal/authentik/users/ensure`）
 Request:
 ```json
 {
@@ -181,7 +182,7 @@ Request:
 Response:
 ```json
 {
-  "idp_user_id": 123,
+  "idp_user_id": "idp-user-id-or-uuid",
   "action": "created"
 }
 ```

docs/LOCAL_DEV_RUNBOOK.md

@@ -16,7 +16,8 @@ npm run dev
 ## 3) 重要環境變數
 - `backend/.env.development`
   - `ADMIN_REQUIRED_GROUPS=member-admin`
-  - `AUTHENTIK_*` 需可連到 Authentik
+  - 優先使用 `KEYCLOAK_*`（若有設定 `KEYCLOAK_BASE_URL + KEYCLOAK_REALM`）
+  - 未設定 Keycloak 時，才使用 `AUTHENTIK_*` 備援
 
 ## 4) 基本檢查
 - `GET http://127.0.0.1:8000/healthz`
@@ -24,7 +25,7 @@ npm run dev
 - 非 admin 群組帳號打 `/admin/*` 應回 `403`
 
 ## 5) 會員流程驗收
-1. 新增會員（username/email/display_name，開啟 sync_to_authentik）
+1. 新增會員（username/email/display_name，開啟 sync_to_authentik；此旗標目前代表「同步到外部 IdP」）
 2. 確認列表可看到新會員與 `user_sub`
 3. 點「重設密碼」，取得臨時密碼
-4. 到 Authentik 驗證該會員可用新密碼登入
+4. 到 Keycloak（或 Authentik）驗證該會員可用新密碼登入