feat(members): split username/display_name, sync updates to authentik, add password reset API and refresh docs

docs/ARCHITECTURE.md

@@ -1,29 +1,26 @@
 # member.ose.tw 架構總覽
 
-## 1) 核心模型
-- 業務層級：`companies -> sites -> users`
-- 功能層級：`systems -> modules`
-- 權限核心：`permission_groups`（群組整合權限與成員）
+## 核心模型
+- 業務層：`companies -> sites -> users`
+- 功能層：`systems -> modules`
+- 權限層：`permission_groups`（群組中心）
 
-## 2) 權限規則（固定）
-- `scope` 只允許：`site`
-- `action` 只允許：`view`、`edit`
-- `view`、`edit` 可同時勾選（多選）
-- 畫面顯示格式：`公司/站台`
+## 權限規則
+- `scope_type` 固定 `site`
+- `action` 僅 `view` / `edit`（可同時存在）
+- 權限透過群組下發給會員，不走細粒度 direct permission 主流程
 
-## 3) 關聯關係（皆為多對多）
-- 群組 ⟷ 站台
-- 群組 ⟷ 系統
-- 群組 ⟷ 模組
-- 群組 ⟷ 會員
+## 後台安全線
+- 所有 `/admin/*` 需 Bearer token
+- 後端僅依 `ADMIN_REQUIRED_GROUPS` 判定可否進後台
+- 不在群組就算有網址、有 Authentik 帳號也會 403
 
-## 4) 管理頁責任
-- 群組管理：群組基本資料 + 站台/系統/模組/會員 + action(view/edit)
-- 系統編輯頁：基本資料 + 所屬群組列表 + 涉及會員列表
-- 模組編輯頁：基本資料 + 所屬群組列表 + 涉及會員列表
-- 公司頁：基本資料 + 站台列表
-- 會員編輯頁：基本資料 + 所屬群組列表
+## 會員資料與 Authentik 對齊
+- `username`：登入帳號（可編輯，可同步）
+- `display_name`：顯示名稱（可編輯，可同步到 Authentik `name`）
+- `authentik_sub`：由 Authentik UID 回寫
+- `authentik_user_id`：保留 Authentik user id，供更新/密碼重設
 
-## 5) 本輪範圍
-- 會員細粒度直接授權先暫停
-- 最終規格書（正式對外版）延後到專案完成後再整理
+## 密碼流程
+- 目前：後台可觸發重設密碼（產生臨時密碼）
+- SMTP 開通後：可再補「發送密碼設定/重設通知」自動化

docs/BACKEND_TASKPLAN.md

@@ -1,22 +1,17 @@
 # Backend TaskPlan
 
 ## 待辦
-- [ ] 重寫 `backend/scripts/init_schema.sql` 為乾淨重建版（drop/recreate）
-- [ ] 刪除非必要舊表與舊權限模型（只留群組中心模型）
-- [ ] 新增/調整查詢 API：
-  - [ ] 系統明細關聯（群組、會員）
-  - [ ] 模組明細關聯（群組、會員）
-  - [ ] 公司底下站台列表
-  - [ ] 會員所屬群組列表
-- [ ] action 驗證改為只允許 `view/edit`
-- [ ] scope 驗證改為只允許 `site`
-- [ ] 補齊 API 錯誤碼一致性（400/404/409）
+- [ ] 補 Authentik SMTP 通知流程（密碼設定/重設寄信）
+- [ ] 補 `/admin/members` 關鍵操作審計日誌
+- [ ] 補更多 API 測試（members username/password reset 路徑）
 
 ## 進行中
-- [ ] 新 schema 與 API 契約對齊設計（以群組整合權限為中心）
+- [ ] 文件與程式持續對齊（避免規格漂移）
 
 ## 已完成
-- [x] 後端已具備 systems/modules/companies/sites/members/permission-groups 基礎 CRUD 能力
-- [x] 本地開發環境（`.env.development`）可啟動並連線 DB
-- [x] 管理 API 認證統一使用 `X-Client-Key` + `X-API-Key`
-- [x] Authentik 會員同步流程已能在 upsert/update 路徑運作
+- [x] `/admin/*` 改為 Bearer + admin 群組管控（`ADMIN_REQUIRED_GROUPS`）
+- [x] 管理 API 完成 systems/modules/companies/sites/members/permission-groups CRUD
+- [x] 會員 upsert/update 可同步 Authentik
+- [x] 會員資料新增 `username` 欄位，與 `display_name` 分離
+- [x] 新增 `POST /admin/members/{authentik_sub}/password/reset`
+- [x] DB 新增 `users.username`（含 migration 腳本）

docs/DB_SCHEMA.md

@@ -1,91 +1,42 @@
-# DB Schema（新架構）
+# DB Schema（現行）
 
-## 1) 設計原則
-- 權限以群組為中心，不使用會員直接細粒度授權流程
-- `scope` 固定為 `site`
-- `action` 只允許 `view`、`edit`（可同時存在）
-- DB 真實執行來源：`backend/scripts/init_schema.sql`
+## 真實來源
+- `backend/scripts/init_schema.sql`
+- 線上增量：`backend/scripts/migrate_add_users_username.sql`
 
-## 2) 核心實體
-- `companies`
-  - `id` (PK)
-  - `company_key` (UNIQUE)
-  - `name`, `status`, `created_at`, `updated_at`
-- `sites`
-  - `id` (PK)
-  - `site_key` (UNIQUE)
-  - `company_id` (FK -> companies.id)
-  - `name`, `status`, `created_at`, `updated_at`
+## 主要表
 - `users`
-  - `id` (PK)
-  - `authentik_sub` (UNIQUE)
-  - `authentik_user_id`, `email` (UNIQUE), `display_name`, `is_active`
+  - `authentik_sub` UNIQUE
+  - `authentik_user_id` INTEGER
+  - `username` UNIQUE
+  - `email` UNIQUE
+  - `display_name`
+  - `is_active`, `status`, timestamps
+- `companies`
+- `sites`（`company_id -> companies.id`）
 - `systems`
-  - `id` (PK)
-  - `system_key` (UNIQUE)
-  - `name`, `status`
-- `modules`
-  - `id` (PK)
-  - `module_key` (UNIQUE)
-  - `system_id` (FK -> systems.id)
-  - `name`, `status`
+- `modules`（`system_key -> systems.system_key`）
 - `permission_groups`
-  - `id` (PK)
-  - `group_key` (UNIQUE)
-  - `name`, `status`
+- `permission_group_members`（group + authentik_sub）
+- `permission_group_permissions`（group + site/system/module/action）
+- `user_scope_permissions`（相容保留）
+- `api_clients`（保留給機器對機器用途）
 
-## 3) 群組關聯（多對多）
-- `permission_group_members`
-  - `group_id` (FK -> permission_groups.id)
-  - `user_id` (FK -> users.id)
-  - UNIQUE (`group_id`, `user_id`)
-- `permission_group_sites`
-  - `group_id` (FK -> permission_groups.id)
-  - `site_id` (FK -> sites.id)
-  - UNIQUE (`group_id`, `site_id`)
-- `permission_group_systems`
-  - `group_id` (FK -> permission_groups.id)
-  - `system_id` (FK -> systems.id)
-  - UNIQUE (`group_id`, `system_id`)
-- `permission_group_modules`
-  - `group_id` (FK -> permission_groups.id)
-  - `module_id` (FK -> modules.id)
-  - UNIQUE (`group_id`, `module_id`)
-- `permission_group_actions`
-  - `group_id` (FK -> permission_groups.id)
-  - `action` (`view` | `edit`)
-  - UNIQUE (`group_id`, `action`)
+## 權限規則
+- `scope_type='site'`
+- `action in ('view','edit')`
 
-## 4) 查詢預期
-- 系統頁關聯：
-  - 查 `permission_group_systems` 取群組
-  - 經 `permission_group_members` 推導涉及會員
-- 模組頁關聯：
-  - 查 `permission_group_modules` 取群組
-  - 經 `permission_group_members` 推導涉及會員
-- 公司頁站台：
-  - 查 `sites` by `company_id`
-- 會員頁群組：
-  - 查 `permission_group_members` by `user_id`
+## 會員與 Authentik 對齊
+- `users.authentik_sub` 對應 Authentik `uid`
+- `users.username` 對應 Authentik `username`
+- `users.display_name` 對應 Authentik `name`
 
-## 5) 驗收查核（SQL）
+## 快速檢查 SQL
 ```sql
--- 1) 檢查主表是否存在
-SELECT tablename
-FROM pg_tables
-WHERE schemaname = 'public'
-  AND tablename IN (
-    'companies','sites','users','systems','modules','permission_groups',
-    'permission_group_members','permission_group_sites',
-    'permission_group_systems','permission_group_modules','permission_group_actions'
-  )
-ORDER BY tablename;
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name='users'
+ORDER BY ordinal_position;
 
--- 2) 檢查 action 值域
-SELECT DISTINCT action FROM permission_group_actions ORDER BY action;
-
--- 3) 檢查群組可同時有 view/edit
-SELECT group_id, array_agg(action ORDER BY action) AS actions
-FROM permission_group_actions
-GROUP BY group_id;
+SELECT COUNT(*) FROM users WHERE username IS NULL;
 ```

docs/FRONTEND_HANDOFF.md

@@ -1,33 +1,17 @@
-# Frontend Handoff（交給前端 AI）
+# Frontend Handoff
 
-## 目標
-把後台管理改為「群組中心權限模型」，並符合以下固定規則：
-- `scope` 只用 `site`
-- 顯示為 `公司/站台`
-- `action` 只允許 `view/edit`，且可多選
+## 目前後端契約重點
+- 後台登入：只吃 Bearer + admin 群組檢查
+- 會員模型：`authentik_sub`, `username`, `email`, `display_name`, `is_active`
+- 會員密碼：支援重設 API（回傳臨時密碼）
 
-## 交辦項目
-1. 群組管理頁
-- 群組基本資料 CRUD
-- 同頁整合：站台、系統、模組、會員、action
-- action 使用多選（`view`、`edit`）
+## 會員頁必做
+1. 新增會員表單欄位：`username`、`email`、`display_name`
+2. 編輯會員表單欄位：`username`、`email`、`display_name`、`is_active`
+3. 表格欄位要顯示：`authentik_sub`、`username`、`email`、`display_name`
+4. 操作欄新增「重設密碼」按鈕，串 `POST /admin/members/{authentik_sub}/password/reset`
+5. 重設成功後顯示臨時密碼，並提醒管理員安全轉交
 
-2. 系統編輯頁
-- 顯示該系統被哪些群組使用
-- 顯示該系統涉及哪些會員（由群組關聯推導）
-
-3. 模組編輯頁
-- 顯示該模組被哪些群組使用
-- 顯示該模組涉及哪些會員（由群組關聯推導）
-
-4. 公司頁
-- 顯示公司底下站台列表
-
-5. 會員編輯頁
-- 顯示/編輯所屬群組
-- 會員直接授權先不做
-
-## 串接約束
-- 只串接新版群組中心 API
-- 不新增最終規格表頁面
-- UI/UX 可另外優化，但資料與流程規則不可改
+## 其他頁面
+- 仍維持群組中心模型：site/system/module/member + action(view/edit)
+- 系統/模組/公司/會員關聯頁面沿用目前 API

docs/FRONTEND_TASKPLAN.md

@@ -1,20 +1,16 @@
 # Frontend TaskPlan
 
 ## 待辦
-- [ ] 重構群組管理頁為單一中心（整合權限設定，不再拆分心智）
-- [ ] 新增系統編輯頁關聯區塊：所屬群組、涉及會員
-- [ ] 新增模組編輯頁關聯區塊：所屬群組、涉及會員
-- [ ] 公司頁新增站台列表區塊
-- [ ] 會員編輯頁強化群組列表與編輯體驗
-- [ ] 所有 action UI 改為多選但僅 `view/edit`
-- [ ] 所有 scope UI 固定為 `site`（顯示 `公司/站台`）
-- [ ] 隱藏/移除會員細粒度直接授權主流程入口
+- [ ] SMTP 通知開通後，補上「發送重設通知」UX 文案
+- [ ] 會員頁重設密碼流程加上二次確認 Dialog
+- [ ] 針對大量資料頁面補分頁/搜尋體驗優化
 
 ## 進行中
-- [ ] 與新版後端 API 契約對齊（群組中心）
+- [ ] 與最新後端契約持續對齊（members username/password reset）
 
 ## 已完成
-- [x] 前端框架採用 Vue3 + JS + Vite + Element Plus + Tailwind
-- [x] 已有 admin 基礎頁面：systems/modules/companies/sites/members/permission-groups
-- [x] 已有會員建立/編輯與群組指派基本能力
-- [x] 已有 OIDC 登入與 `/me`、`/me/permissions/snapshot` 基礎流程
+- [x] Vue3 + JS + Vite + Element Plus + Tailwind 基礎架構
+- [x] admin 基礎頁面：systems/modules/companies/sites/members/permission-groups
+- [x] 會員頁新增 `username` 欄位（新增/編輯/列表）
+- [x] 會員頁新增「重設密碼」操作按鈕
+- [x] OIDC 登入 + `/me`、`/me/permissions/snapshot` 流程

docs/LOCAL_DEV_RUNBOOK.md

@@ -3,7 +3,7 @@
 ## 1) 啟動後端
 ```bash
 cd backend
-.venv/bin/uvicorn app.main:app --env-file .env.development --host 127.0.0.1 --port 8000
+./scripts/start_dev.sh
 ```
 
 ## 2) 啟動前端
@@ -13,19 +13,18 @@ npm install
 npm run dev
 ```
 
-## 3) 基本檢查
-- Backend health: `GET http://127.0.0.1:8000/healthz`
-- Frontend: `http://localhost:5173` 或 `http://127.0.0.1:5173`
-- 檢查 admin API 是否有自動帶 `X-Client-Key`、`X-API-Key`
+## 3) 重要環境變數
+- `backend/.env.development`
+  - `ADMIN_REQUIRED_GROUPS=member-admin`
+  - `AUTHENTIK_*` 需可連到 Authentik
 
-## 4) 驗收順序（本地）
-1. 建立公司、站台
-2. 建立系統、模組
-3. 建立會員
-4. 建立群組
-5. 在群組配置：站台/系統/模組/action(view/edit)/會員
-6. 到系統/模組/公司/會員頁確認關聯列表是否正確
+## 4) 基本檢查
+- `GET http://127.0.0.1:8000/healthz`
+- 登入後打 `GET /admin/members` 應可回資料
+- 非 admin 群組帳號打 `/admin/*` 應回 `403`
 
-## 5) 注意事項
-- 本輪不產最終規格表
-- DB 真實來源僅 `backend/scripts/init_schema.sql`
+## 5) 會員流程驗收
+1. 新增會員（username/email/display_name，開啟 sync_to_authentik）
+2. 確認列表可看到新會員與 `authentik_sub`
+3. 點「重設密碼」，取得臨時密碼
+4. 到 Authentik 驗證該會員可用新密碼登入

docs/index.md

@@ -1,6 +1,6 @@
 # member.ose.tw 文件入口
 
-## 閱讀順序（先看）
+## 閱讀順序
 1. `docs/ARCHITECTURE.md`
 2. `docs/DB_SCHEMA.md`
 3. `docs/BACKEND_TASKPLAN.md`
@@ -8,16 +8,14 @@
 5. `docs/FRONTEND_HANDOFF.md`
 6. `docs/LOCAL_DEV_RUNBOOK.md`
 
-## 交辦順序（執行）
-1. 後端先完成新 schema 與 API 契約
-2. 前端依 handoff 完成頁面與串接
-3. 本地驗收跑 Runbook
-
 ## 目前狀態
-- 架構方向：已定版（群組中心、site scope、action view/edit 多選）
-- 文件重整：已完成（舊文件已清除）
-- 程式重構：待後續依 TaskPlan 實作
+- 架構：公司/站台/會員 + 系統/模組 + 群組整合權限（已定版）
+- 後台安全：Auth token + admin 群組檢查（`ADMIN_REQUIRED_GROUPS`）
+- 會員流程：member 新增/更新可同步 Authentik，並支援重設密碼
+
+## 單一真實來源
+- DB SQL：`backend/scripts/init_schema.sql`
+- DB 線上補丁：`backend/scripts/migrate_add_users_username.sql`
 
 ## 備註
-- 本輪不產最終規格表/最終規範矩陣
-- DB 文檔以 `docs/DB_SCHEMA.md` 為說明入口，實際 SQL 以 `backend/scripts/init_schema.sql` 為準
+- 本輪先維持可開發/可交辦文件，不產最終規格總表。