feat(flow): unify member-group-permission admin workflow and docs

2026-03-30 03:54:22 +08:00
parent 31fff92e19
commit f884f1043d
17 changed files with 576 additions and 130 deletions
--- a/docs/BACKEND_ARCHITECTURE.md
+++ b/docs/BACKEND_ARCHITECTURE.md
@@ -1,37 +1,52 @@
-# memberapi.ose.tw 後端架構（公司/品牌站台/會員）
+# memberapi.ose.tw 後端架構（公司/品牌站台/會員 + 系統/模組權限）

-## 核心主檔（對齊 DB Schema）
- `users`：會員
- `companies`：公司
- `sites`：品牌站台（隸屬 company）
- `systems`：系統層（member/mkt/...）
- `modules`：模組（使用 `system.module` key）
+## 資料層級
+- 業務層級：`companies -> sites -> users`
+- 功能層級：`systems -> modules`
+- 授權掛載點：
+  - Scope：`company` 或 `site`
+  - 能力：`system` 必填，`module` 選填（空值代表系統層）

 ## 權限模型
- 直接權限：`user_scope_permissions`
- 群組權限：`permission_groups` + `permission_group_members` + `permission_group_permissions`
- Snapshot 回傳：合併「user 直接 + group」去重
+- 直接授權：`user_scope_permissions`
+- 群組授權：`permission_groups` + `permission_group_members` + `permission_group_permissions`
+- 權限快照：`/me/permissions/snapshot` 會合併「直接 + 群組」並去重

-## 授權層級
- `system` 必填
- `module` 選填
-  - 有值：`{system}.{module}`（例：`mkt.campaign`）
-  - 無值：系統層權限，使用 `system.__system__`
+## 目前後端 API（管理面）
+- 主資料：
+  - `GET|POST|PATCH /admin/systems`
+  - `GET|POST|PATCH /admin/modules`
+  - `GET|POST|PATCH /admin/companies`
+  - `GET|POST|PATCH /admin/sites`
+- 會員：
+  - `GET /admin/members`
+  - `POST /admin/members/upsert`
+  - `PATCH /admin/members/{authentik_sub}`
+- 會員群組（改由會員頁管理）：
+  - `GET /admin/members/{authentik_sub}/permission-groups`
+  - `PUT /admin/members/{authentik_sub}/permission-groups`
+- 群組：
+  - `GET|POST|PATCH /admin/permission-groups`
+  - `GET /admin/permission-groups/{group_key}/permissions`
+  - `POST /admin/permission-groups/{group_key}/permissions/grant`
+  - `POST /admin/permission-groups/{group_key}/permissions/revoke`
+- 直接授權：
+  - `POST /admin/permissions/grant`
+  - `POST /admin/permissions/revoke`
+  - `GET /admin/permissions/direct`
+  - `DELETE /admin/permissions/direct/{permission_id}`

-## 主要 API
- `GET /me`
- `GET /me/permissions/snapshot`
- `POST /admin/permissions/grant|revoke`
- `GET|POST /admin/systems`
- `GET|POST /admin/modules`
- `GET|POST /admin/companies`
- `GET|POST /admin/sites`
- `GET /admin/members`
- `GET|POST /admin/permission-groups`
- `POST|DELETE /admin/permission-groups/{group_key}/members/{authentik_sub}`
- `POST /admin/permission-groups/{group_key}/permissions/grant|revoke`
- `GET /internal/systems|modules|companies|sites|members`
+## 驗證與查詢 API
+- 使用者端：
+  - `GET /me`
+  - `GET /me/permissions/snapshot`
+- OIDC：
+  - `GET /auth/oidc/url`
+  - `POST /auth/oidc/exchange`
+- Internal（跨系統查詢）：
+  - `GET /internal/systems|modules|companies|sites|members`
+  - `GET /internal/permissions/{authentik_sub}/snapshot`

-## DB Migration
- 初始化：`backend/scripts/init_schema.sql`
- 舊庫補齊：`backend/scripts/migrate_align_company_site_member_system.sql`
+## DB 與初始化
+- 統一 schema：`backend/scripts/init_schema.sql`
+- schema 快照：`docs/DB_SCHEMA_SNAPSHOT.md`
--- a/docs/FRONTEND_API_CONTRACT.md
+++ b/docs/FRONTEND_API_CONTRACT.md
@@ -61,26 +61,48 @@ Headers:
 - `X-Client-Key`
 - `X-API-Key`

- `GET/POST /admin/systems`
- `GET/POST /admin/modules`
- `GET/POST /admin/companies`
- `GET/POST /admin/sites`
+- `GET/POST/PATCH /admin/systems`
+- `GET/POST/PATCH /admin/modules`
+- `GET/POST/PATCH /admin/companies`
+- `GET/POST/PATCH /admin/sites`
 - `GET /admin/members`
+- `POST /admin/members/upsert`
+- `PATCH /admin/members/{authentik_sub}`

-## 4. 權限群組（一組權限綁多個 user）
+## 4. 會員與群組關聯（由會員頁管理）
 Headers:
 - `X-Client-Key`
 - `X-API-Key`

- `GET/POST /admin/permission-groups`
- `POST /admin/permission-groups/{group_key}/members/{authentik_sub}`
- `DELETE /admin/permission-groups/{group_key}/members/{authentik_sub}`
+- `GET /admin/members/{authentik_sub}/permission-groups`
+- `PUT /admin/members/{authentik_sub}/permission-groups`
+```json
+{
+  "group_keys": ["site-ops", "mkt-admin"]
+}
+```
+
+## 5. 權限群組（一組權限可綁多個 user）
+Headers:
+- `X-Client-Key`
+- `X-API-Key`
+
+- `GET/POST/PATCH /admin/permission-groups`
+- `GET /admin/permission-groups/{group_key}/permissions`
 - `POST /admin/permission-groups/{group_key}/permissions/grant`
 - `POST /admin/permission-groups/{group_key}/permissions/revoke`

 群組授權 payload 與 user 授權 payload 相同（用 `system/module/scope/action`）。

-## 5. Internal 查詢 API（其他系統）
+## 6. 直接授權列表（權限管理頁）
+Headers:
+- `X-Client-Key`
+- `X-API-Key`
+
+- `GET /admin/permissions/direct?keyword=&scope_type=&limit=&offset=`
+- `DELETE /admin/permissions/direct/{permission_id}`
+
+## 7. Internal 查詢 API（其他系統）
 Headers:
 - `X-Internal-Secret`

@@ -91,10 +113,11 @@ Headers:
 - `GET /internal/members`
 - `GET /internal/permissions/{authentik_sub}/snapshot`

-## 6. 常見錯誤
+## 8. 常見錯誤
 - `401 invalid_client`
 - `401 invalid_api_key`
 - `401 invalid_internal_secret`
 - `404 system_not_found`
 - `404 company_not_found`
 - `404 site_not_found`
+- `400 invalid_permission_id`
--- a/docs/FRONTEND_HANDOFF_SCHEMA_V2.md
+++ b/docs/FRONTEND_HANDOFF_SCHEMA_V2.md
@@ -1,4 +1,4 @@
-# Frontend 交辦清單（Schema v2）✅ 已完成
+# Frontend 交辦清單（Schema v2）

 ## 目標
 前端實現對應後端新模型：
@@ -60,23 +60,27 @@
 - [x] 表格顯示三個欄位
 - [x] Dialog 表單新增站台

-### 7) 會員列表 `/admin/members` ✅
+### 7) 會員管理 `/admin/members` ✅
 - [x] 列表：`GET /admin/members`
 - [x] 表格顯示 authentik_sub、email、display_name
- [x] 可重新整理
+- [x] 新增會員：`POST /admin/members/upsert`
+- [x] 編輯會員：`PATCH /admin/members/{authentik_sub}`
+- [x] 會員頁可直接設定「權限群組」（multi-select）：
+  - [x] `GET /admin/members/{authentik_sub}/permission-groups`
+  - [x] `PUT /admin/members/{authentik_sub}/permission-groups`

 ### 8) 權限群組 `/admin/permission-groups` ✅
 - [x] 群組管理 Tab：
  - [x] 列表：`GET /admin/permission-groups`
  - [x] 新增：`POST /admin/permission-groups`
  - [x] Dialog 表單新增群組
- [x] 綁定會員 Tab：
-  - [x] `POST /admin/permission-groups/{group_key}/members/{authentik_sub}`
-  - [x] UI 支援群組選擇 + authentik_sub 輸入 + 加入按鈕
 - [x] 群組授權 Tab：
  - [x] `POST /admin/permission-groups/{group_key}/permissions/grant`
  - [x] `POST /admin/permission-groups/{group_key}/permissions/revoke`
  - [x] UI 支援選擇群組、輸入權限資訊、grant/revoke 按鈕
+- [x] 群組權限列表：
+  - [x] `GET /admin/permission-groups/{group_key}/permissions`
+  - [x] 可查看群組目前有哪些系統/模組/操作權限

 ## 共用資料管理 ✅
 - [x] admin.js store 實現：
@@ -88,11 +92,19 @@
  - [x] `X-Client-Key`
  - [x] `X-API-Key`
 - [x] axios adminHttp client 自動注入 headers
+- [x] 管理頁不需手動輸入金鑰（改由環境變數與攔截器帶入）
+
+## 權限管理頁強化 ✅
+- [x] 直接授權列表：
+  - [x] `GET /admin/permissions/direct`
+  - [x] 支援關鍵字與 scope 篩選
+- [x] 列表逐筆撤銷：
+  - [x] `DELETE /admin/permissions/direct/{permission_id}`

 ## 驗收條件 ✅
 - [x] 可以新增 system/module/company/site
 - [x] 可以做 user 直接 grant/revoke（新 payload）
- [x] 可以建立 permission-group、加會員、做群組 grant/revoke
+- [x] 可以建立 permission-group，並在會員頁指派群組，做群組 grant/revoke
 - [x] `/me/permissions/snapshot` 能看到所有權限欄位（scope_type/scope_id/system/module/action）

 ## 完成日期
--- a/docs/TASKPLAN_FRONTEND.md
+++ b/docs/TASKPLAN_FRONTEND.md
@@ -35,8 +35,8 @@
  - [x] `/admin/modules`（模組 CRUD）
  - [x] `/admin/companies`（公司 CRUD）
  - [x] `/admin/sites`（站台 CRUD）
-  - [x] `/admin/members`（會員列表）
-  - [x] `/admin/permission-groups`（群組 CRUD + 綁會員 + 群組授權）
+  - [x] `/admin/members`（會員 CRUD + 指派群組）
+  - [x] `/admin/permission-groups`（群組 CRUD + 群組授權 + 群組權限列表）
 - [x] 導覽列加入管理員群組下拉菜單

 ## 進行中（下一階段）
@@ -55,6 +55,6 @@
 - [x] 登入後可穩定讀取 `/me` 與快照 ✅
 - [x] 可新增 system/module/company/site ✅
 - [x] 可做用戶直接 grant/revoke（新 payload） ✅
- [x] 可建立 permission-group、加會員、群組 grant/revoke ✅
+- [x] 可建立 permission-group，並從會員頁指派群組，做群組 grant/revoke ✅
 - [x] `/me/permissions/snapshot` 表格可顯示 system + module + action ✅
 - [x] 與後端契約文件一致 ✅
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,24 +1,38 @@
 # member docs index

-## 先看這三份
-1. `docs/FRONTEND_ARCHITECTURE.md`
-2. `docs/FRONTEND_API_CONTRACT.md`
-3. `docs/FRONTEND_IMPLEMENTATION_CHECKLIST.md`
+## 0. 先看這兩份（入口）
+1. `docs/ARCHITECTURE_AND_CONFIG.md`
+2. `docs/BACKEND_ARCHITECTURE.md`

-## 系統架構與後端
- `docs/ARCHITECTURE_AND_CONFIG.md`
- `docs/BACKEND_ARCHITECTURE.md`
+## 1. 架構核心（你現在的實際模型）
+- 業務層級：`公司 companies -> 品牌站台 sites -> 會員 users`
+- 功能層級：`系統 systems -> 模組 modules`
+- 授權層級：`scope(company/site) + system + module(可空) + action`
+- 權限來源：`直接授權 + 群組授權`
+
+## 2. 前端交辦（直接丟給另一隻 AI）
+1. `docs/FRONTEND_API_CONTRACT.md`
+2. `docs/FRONTEND_HANDOFF_SCHEMA_V2.md`
+3. `docs/FRONTEND_ARCHITECTURE.md`
+
+## 3. 後端與環境
 - `docs/BACKEND_BOOTSTRAP.md`
-
-## 任務管理
- `docs/TASKPLAN_FRONTEND.md`
 - `docs/TASKPLAN_BACKEND.md`
- `docs/ORG_MEMBER_MANAGEMENT_PLAN.md`（公司組織/會員管理規劃）
- `docs/FRONTEND_HANDOFF_SCHEMA_V2.md`（前端交辦清單，直接給另一隻 AI）
+- `backend/.env.development`（本機開發）

-## SQL 與配置
- `backend/scripts/init_schema.sql`
- `docs/DB_SCHEMA_SNAPSHOT.md`
+## 4. DB（單一來源）
+- `backend/scripts/init_schema.sql`（完整 schema）
+- `docs/DB_SCHEMA_SNAPSHOT.md`（目前資料庫結構快照）

-## 給前端 AI 的一句話交接
-請先完成 `/me`、`/me/permissions/snapshot`、`/admin/permissions/grant|revoke` 三組 API 對接，並依 `FRONTEND_IMPLEMENTATION_CHECKLIST.md` 逐項完成。
+## 5. 管理流程（建議操作順序）
+1. 建立 `systems`、`modules`
+2. 建立 `companies`、`sites`
+3. 建立/同步 `members`（可同步 Authentik）
+4. 建立 `permission-groups`
+5. 在會員頁指定會員所屬群組
+6. 在權限頁做直接授權，或在群組頁做群組授權
+
+## 6. 前端頁面責任切分
+- 會員頁：會員基本資料 + 群組指派
+- 群組頁：群組 CRUD + 群組權限列表 + 群組授權/撤銷
+- 權限管理頁：直接授權/撤銷 + 直接授權列表（可逐筆撤銷）