refactor: rebuild backend around role-site authorization model

docs/INTERNAL_API_HANDOFF.md

@@ -13,26 +13,38 @@
 { "detail": "error_code" }
 ```
 
-## 資源模型（重點）
-- `company`: `id`, `company_key`, `display_name`, `legal_name`, `status`
-- `site`: `id`, `site_key`, `company_id`, `display_name`, `domain`, `status`
-- `system`: `id`, `system_key`, `name`, `idp_client_id`, `status`
-- `role`: `id`, `role_key`, `system_id`, `name`, `description`, `idp_role_name`, `status`
-- `user`: `id`, `user_sub`, `username`, `email`, `display_name`, `is_active`, `status`
-
-## 主要端點（目標）
+## 已實作端點
 1. `GET /internal/companies`
 2. `GET /internal/sites`
 3. `GET /internal/systems`
 4. `GET /internal/roles`
-5. `GET /internal/users`
-6. `GET /internal/users/{user_sub}/roles`
-- 回傳該 user 透過 site 推導出的最終 roles。
+5. `GET /internal/members`
+6. `POST /internal/users/upsert-by-sub`
+7. `GET /internal/users/{user_sub}/roles`
+8. `GET /internal/permissions/{user_sub}/snapshot`（相容路徑，回 role 聚合資料）
+9. `POST /internal/idp/users/ensure`
+10. `POST /internal/keycloak/users/ensure`
 
-## 關聯端點（目標）
-1. `POST /internal/site-roles` / `DELETE /internal/site-roles/{id}`
-2. `POST /internal/user-sites` / `DELETE /internal/user-sites/{id}`
+## 角色聚合回應（`GET /internal/users/{user_sub}/roles`）
+```json
+{
+  "user_sub": "xxxxxxxx",
+  "roles": [
+    {
+      "site_key": "ST20260402X1234",
+      "site_display_name": "OSE Main",
+      "company_key": "CP20260402X5678",
+      "company_display_name": "OSE",
+      "system_key": "SY20260402X0001",
+      "system_name": "Marketing",
+      "role_key": "RL20260402X0002",
+      "role_name": "campaign_edit",
+      "idp_role_name": "campaign_edit"
+    }
+  ]
+}
+```
 
 ## 注意事項
 - 不提供 user direct role 寫入 API。
-- 若其他系統需要判斷某 user 可否做某事，請吃 `users/{user_sub}/roles` 聚合結果。
+- User 最終角色由 `user_sites` + `site_roles` 推導。