使用者表單（User Form）

功能群：系統管理｜三層 RBAC 模型與租戶／部門組織模型先讀 功能群總覽 §2、§3｜上層導航頁見 使用者管理

事實基準：2026-07-05 從 FE src/views/user-manage/UserMTRBACForm.vue（641 行）+ BE api/auth/routes/user_route.py / change_password_route.py + jedi-auth user_service.py / user_domain_service.py + routes.json / db_schema.json 掃出。

變更紀錄

1. 功能描述

使用者表單是 使用者管理 列表「建立」/「編輯」導向的獨立表單頁（route user-form，實掛 /auth/user-form-mtrbac → UserMTRBACForm.vue）。新增與編輯共用同一表單：上半填帳號基本欄位（登入名稱 / 姓名 / Email / 職稱 / 電話 / 生效到期日 /（編輯限定）代改密碼），下半以 DataTable 維護「租戶 × 部門 × 角色」的授權組合（多筆，恰一筆為預設）。儲存時基本欄位與授權組合陣列一起送出，user_roles / tenants / org_units 三表全量取代。

主要使用者：系統 / 租戶管理員。權限治理（角色如何綁能力）由 角色權限管理 負責；本頁只做「使用者 ↔︎ 角色／租戶／部門」的指派。

角色速覽（完整定義見 _overview §2、§3）：

⚠️ route 命名陷阱：FE views/user-manage/UserForm.vue（463 行）是死碼——router 中對應的 /auth/user-form route 已整段註解掉（config/router/index.js:138-145）。目前 user-form（name）這個路由名實際指向 /auth/user-form-mtrbac → UserMTRBACForm.vue（641 行，multi-tenant RBAC 版表單），本 spec 全部以此為準，不描述 UserForm.vue 的行為。

1.1 功能總覽（本頁全部功能）

展開成 UC：UC-USER-01（建立 / 編輯帳號主流程）、UC-USER-02（授權組合指派）。停用 / 刪除 / 列表操作屬 使用者管理 hub。

2. Use Case

角色速覽（完整定義見 _overview §2、§3）：

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點。

UC-USER-01 建立 / 編輯帳號

UC-USER-02 授權組合（租戶 × 部門 × 角色）指派

3. 權限矩陣

專案層 RBAC 基調見 _overview §5。本頁的實際檢查點：

⚠️ 本頁寫入端點缺角色守門：UserRoute 全部 method 皆只掛 @jwt_required()，jedi-auth user_service.add_user/update_user 內部也無角色或能力檢查——任何已登入帳號皆可透過直打 API 新增 / 編輯他人帳號（含 admin，因「不可動 admin」只是 FE 隱藏按鈕）。唯一的例外是密碼代改：update_user 內有 can_change_password 明確擋非管理員改他人密碼。與 _overview §5 及 role-manage.md §3 一致（本群多頁通病）。收進 §12，也見 使用者管理 §12。

4. 狀態機與前置條件

帳號本身狀態（users.status）與列表操作 gate 見 使用者管理 §4。本表單頁 gate：

5. UI 設計

📸 實機截圖待補（亮色模式）。待補清單：表單頁上半基本欄位、表單頁下半授權組合列表、新增/編輯授權組合 Dialog、admin 帳號鎖死狀態（生效/到期日禁用）。

表單頁骨架

狀態呈現：表單頁儲存 / 讀取中蓋一層全螢幕遮罩 + ProgressSpinner（submitted / loading 兩個獨立旗標，避免進頁誤顯示「儲存中」）。

6. API 規格

Envelope：成功 {"code": 1, "data": …}、失敗 {"code": 0, "msg": "…"}。

6.1 總清單（本頁呼叫的全部 endpoint）

列表 / 狀態變更 / 刪除 / Excel 匯入端點見 使用者管理 §6 與 Excel 批次匯入 §6。

6.2 使用者 CRUD（request / response）

[GET] /api/1.0/user/

Response：UserResponse（exclude salt/password），額外含 auth_providers[]（UserAuthProviderResponse）。欄位卡見 使用者管理 §6.2 列表回傳。出處：user_route.py:57-73。

[POST] /api/1.0/user（建立）／ [PUT] /api/1.0/user/（更新）

Request（UserRequest，api/auth/serializers/user.py:5-19）：

Response：同 GET（exclude salt/password/last_login_success_time/last_login_failed_time）。

BE 鏈路：UserRoute.post/put（user_route.py:75-101）→ jedi-auth UserService.add_user / update_user（user_service.py:100-338）。關鍵行為：

• 授權組合陣列的第一筆或標 is_default 的那筆決定 user_entity.tenant_id / org_unit_id（使用者的預設租戶/部門欄位）
• tenants / org_units / user_roles 三者在 update_user 時先刪後插（全量取代）：user_tenant_domain_service.delete_by_user → 重建；user_org_unit_domain_service.delete_by_user → 重建；user_role_domain_service.delete_user_role_by_user_id → 重建
• 新增時若 password 未帶，generate_complex_password(12) 自動產生亂碼密碼，寄送帳號建立通知信（含明碼密碼，僅信件內、不落 log；user_service.py:102-104 明確禁止把含密碼的 kwargs 整包 dump 進 log）
• 編輯改密碼：非 is_admin 呼叫者會先過 can_change_password(curr_user.uid, uid)（只能改自己），並寫入 user_change_pwd_logs
• 檢核順序：login_name 重複 → email 重複 → 租戶存在 → 部門存在 → 角色存在（uid 清單）

出處：user_service.py:99-214（add_user）、:216-338（update_user）。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖

DDD 提醒：使用者 CRUD 的 route 直接注入 jedi-auth 的 UserService，主專案在這條鏈路無 app service 包裝。大半 domain 邏輯在 jedi-auth 套件（~/Projects/Jedicogy/module/jedi-python-package/jedi-auth/），改行為要分清邊界（CLAUDE.md 外部套件異動規範）。此鏈路模式與 role-manage.md §8 相同（本群通用模式）。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.2 ER 圖

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

public.users — 帳號本體

public.user_roles — 授權組合（本頁核心寫入表）

public.user_tenants / public.user_org_units — 租戶 / 部門歸屬

user_tenants：user_id / tenant_id / is_default / starts_at / ends_at；user_org_units：user_id / org_unit_id / is_primary / starts_at / ends_at。兩表在 update_user 時皆 delete_by_user 後依 user_roles 推導的租戶／部門集合重建（全量取代，非差異更新）。

public.user_change_password_request / public.user_change_pwd_logs

user_change_password_request：uid / user_id / type（0 首次註冊 / 1 密碼重設 / 2 忘記密碼 / 3 密碼過期 / 9 自行變更）/ status（0 未使用 / 1 已使用）/ expired；新增使用者時固定建一筆 type=FIRST_REGISTER、7 天後過期。user_change_pwd_logs：user_id / type / password（加密後）；僅管理員代改密碼成功時寫入一筆。

public.user_auth_providers（唯讀）

uid / user_id / provider / provider_user_id：第三方登入綁定，本頁 GET 明細會回傳但無編輯 UI。

10. 頁面邏輯與資料對應

表單載入時序：

關鍵欄位對應（API ↔︎ 畫面）：

儲存流程：表單整包送出（非逐欄位獨立儲存，不同於專案規劃頁）；onSaveClick 先跑 vuelidate（基本欄位必填 + 密碼強度規則：≥12 碼、含大小寫與數字），通過才組 payload 呼叫 POST /user（新增）或 PUT /user/<uid>（編輯）；成功後導回列表（router.push({name:'user-manage'})）。

錯誤對應：BE error envelope → toast 顯示；常見碼：AUTH_409001（login_name 已存在）、AUTH_409002（email 已存在）、AUTH_404005（租戶不存在）、AUTH_404004（部門不存在）、AUTH_404003（角色不存在）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. UserForm.vue 是死碼：463 行完整表單元件，但 router 對應 /auth/user-form route 整段被註解、無任何 import 引用；實際生效的是 UserMTRBACForm.vue（multi-tenant RBAC 版）。維護時勿誤改死碼。
2. 本頁寫入端點缺角色守門（同 角色權限管理 模式）：UserRoute 全部 method 僅 @jwt_required()，jedi-auth service 層也無角色 / 能力檢查——任何登入帳號可直打 API 新增 / 編輯任何人（含 admin）。唯一的例外：改他人密碼有 can_change_password 明確擋非 is_admin 者。本 spec 只記錄不修。
3. user_roles/tenants/org_units 三表皆全量取代：update_user 對這三個關聯先 delete_by_user 再重建；FE 表單編輯時務必先讀回完整既有授權組合再送出，漏帶等於刪除該筆授權。
4. users.tenant_id/org_unit_id（預設值）由 user_roles 反推，非獨立輸入：新增/編輯時，若送出的授權組合都沒有標 is_default，BE 會強制把第一筆設為預設（user_service.py:122-126,239-243），可能與使用者原意不符（FE 已同步這條規則於本地陣列操作，但兩端各自實作、非共用單一 source）。
5. 敏感欄位（salt/password/topt_secret）一律 exclude：GET/POST/PUT response 都手動 UserResponse(exclude=["salt","password", ...])，新增回傳欄位或改 serializer 務必保留這個 exclude list，避免意外外洩雜湊密碼。
6. nickname 在 BE serializer 非 required，但 FE vuelidate 端強制必填：兩端必填集合不完全對稱（BE UserRequest.nickname 無 required=True），直打 API 可送出無 nickname 的使用者。
7. admin 帳號的鎖死規則分散在多處判斷（生效/到期日禁用、新增授權禁用、既有授權列編輯/刪除禁用）：皆為 FE isTargetAdmin / 字串比對 login_name==='admin'，BE 無對應保護（見坑 2）——非 FE 判斷點若新增功能，記得同步排除 admin。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）。
• 測試帳號：管理員帳號見 memory reference_dev_login / .env（憑證不寫入本文件）。
• 導航路徑：登入 → 側選單「系統管理」→「使用者管理」（/auth/user-manage）→ 建立 / 點某列「編輯」進表單頁。
• 前置資料：至少一個租戶 + 一個部門 + 一個角色（tenant_id NULL 的系統角色亦可）才能完成授權組合指派。
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；本頁相關 feature 檔以 使用者管理 / user-form 搜尋。
• 相關文件：上層導航 使用者管理；Excel 批次匯入；權限系統設計說明書 docs/system-design/permission/；角色權限管理；功能群總覽。