個人資料（User Profile）

功能群：系統管理｜三層 RBAC 模型與共用權限模型先讀 功能群總覽 §2、§5

事實基準：2026-07-05 從 FE src/views/user-manage/UserProfileForm.vue + BE api/auth/routes/user_route.py / api/auth/routes/otp_route.py / api/user_auth_provider/routes/user_auth_provider_route.py + jedi-auth user_service.py / jedi-mfa totp_service.py + routes.json / db_schema.json 掃出

變更紀錄：2026-07-09 FR-047 已知坑修復 —— MFA 切換改「驗證後即時生效」（新增 POST /totp-verify + PUT /user-mfa-type、帳號安全拆卡、B 案不再依附基本資料儲存）；改密「新舊密碼相同」錯誤碼 AUTH_401009→AUTH_400003；TotpQrcodeRoute MFAService 型別統一為 "totp"

1. 功能描述

個人資料頁是使用者操作自己帳號的自助頁面：檢視自身基本資料與所屬角色／租戶／部門（唯讀顯示）、編輯可改欄位、變更密碼、綁定／解除 LDAP 第三方登入、開關 TOTP 兩階段驗證。全頁只有一顆「儲存」鈕，一次 PUT 送出全部欄位（改密與否由密碼欄位是否填寫決定）；LDAP 綁定/解除與 TOTP QR Code 顯示則各自獨立即時呼叫 API。

主要使用者：任何已登入使用者（僅能操作自己）。

角色速覽

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

展開成 UC：UC-PROFILE-01（變更密碼）、UC-PROFILE-02（TOTP 綁定）。LDAP 綁定/解除屬常規 CRUD，於 §6.4 詳述 request/response 但不獨立畫流程圖。

2. Use Case

角色速覽

視覺慣例：判斷框（黃菱形）= 分支條件；橙框 = 擋下 / 例外；紅框 = 錯誤（標 error code）；綠橢圓 = 成功終點。

UC-PROFILE-01 變更密碼

UC-PROFILE-02 綁定 TOTP 兩階段驗證

本頁 TOTP 綁定流程沒有「輸入 Authenticator 動態碼驗證成功才算啟用」的步驟——按開關即建立 secret、按「顯示 QR Code」即可看到密鑰，儲存表單即把 mfa_type 改成 totp 生效，過程不驗證使用者是否真的掃描成功。OTP 驗證頁（/otp-verify、OtpVerification.vue）是登入流程專用（登入時輸入動態碼換 JWT），與本頁綁定流程是兩條不同路徑，不要混淆。見 §12 坑 1。

3. 權限矩陣

本頁角色基調見 _overview §5：個人資料 / 改密 / MFA = 使用者本人操作，理論上僅需 JWT。實際逐項對照：

⚠️ 本頁最大的風險是 GET /user/ 與 TOTP QR Code 端點都沒有自身限定：写入端點（PUT /user-profile）有擋，但兩個讀端點缺角色/自身檢查，屬已知缺口，收進 §12（與 _overview §5 一致：本群多頁的通病，spec 只記錄不修）。

4. 狀態機與前置條件

本頁沒有頁面級狀態機（不隨稽核輪次 / 審核狀態變化），gate 都在欄位與操作層級：

5. UI 設計

📸 實機截圖待補（亮色模式，另有專責 session）。待補清單：Profile Header（頭像/Tag）、基本資料表單區塊、帳號安全區塊（LDAP 卡片 + TOTP 卡片兩狀態：未綁定/已綁定、email/totp）、變更密碼區塊、TOTP QR Code 對話框、LDAP 綁定對話框。

版面骨架（單一表單頁，三區塊縱向排列）：

狀態呈現：LDAP／TOTP 卡片各自用 Tag（綠 enable / 灰 disable）標示目前狀態；全頁載入中與送出中共用同一個全螢幕遮罩 ProgressSpinner（pageLoading || submitted）。無 per-欄位 spinner、無 socket。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "…", "msg": "…"}（HTTP 4xx/5xx）。

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

endpoint 存在性已對 scripts/deliverables/out/routes.json 核實。/otp-verify、/otp-resend 屬登入流程（OtpVerification.vue），本頁不呼叫，不列入本頁清單。

6.2 [GET] /user/{uid}

Response data（節錄本頁使用欄位；完整欄位見 UserResponse，api/auth/serializers/user.py:36-75）：

Response 排除 salt / password（UserResponse(exclude=["salt", "password"])，user_route.py:72）。出處：api/auth/routes/user_route.py:57-73。

6.3 [PUT] /user-profile/{uid}

Request（UserRequest(unknown=INCLUDE)，api/auth/serializers/user.py:5-19；本頁實際填的子集）：

Response：同 GET /user/<uid>（UserResponse(exclude=["salt","password","last_login_success_time","last_login_failed_time"])）。出處：api/auth/routes/user_route.py:141-156（UserProfileRoute.put）→ jedi-auth UserService.update_user（user_service.py:216-338）。

改密副作用鏈（僅當 password 有值）：can_change_password(curr_uid, uid) 二次確認自身 → verify_user_change_password_log（24hr 冷卻 + 近 3 次重複檢查）→ bcrypt 用既有 salt 雜湊 → 寫 user_change_pwd_logs（type=USER_CHANGE_SELF）。出處：user_service.py:268-336。

6.4 LDAP 綁定 / 解除

[POST] /auth-provider（UserAuthProviderRegisterRequest，api/user_auth_provider/serializers/user_auth_provider.py:4-8）：

Response（UserAuthProviderResponse）：

出處：api/user_auth_provider/routes/user_auth_provider_route.py:34-76 → jedi-login UserAuthProviderService.register_user_auth_provider → register_ldap_user（user_auth_provider_service.py:104-129，內部呼叫 ldap_adapter.verify_user 真實驗證帳密後才寫入）。

[DELETE] /auth-provider/{uid}：uid 為 user_auth_providers.uid（該筆綁定記錄本身的 uid，非使用者 uid）。Response：BooleanResponse。出處：同檔 :78-84。

6.5 TOTP

[POST] /totp-secret：無 body（對象固定是 get_user_context() 目前登入者）。Response data：TOTP 註冊結果（secret/provisioning URI 相關，供 debug；FE 本頁未直接使用回傳值，只用來觸發建立）。出處：otp_route.py:24-44（TotpSecretRoute.post）→ jedi-mfa TotpMfaService.register → TotpSecretDomainService.set_totp_secret（既有 secret 則 idempotent 回傳原值，不重建）。

[GET] /otp-qrcode/{uid}：無 body。Response：image/png（send_file，非 JSON envelope）。FE 直接把此 URL 當 <img src>。出處：otp_route.py:46-61（TotpQrcodeRoute.get）→ TotpSecretDomainService.get_totp_secret_qrcode_img（讀 totp_secrets.uri 產生 QR 圖）。

程式碼細節：TotpQrcodeRoute.get 內用 MFAService("email").provider 建構 TotpMfaService（otp_route.py:57），與其他 TOTP 端點用 MFAService("totp")不一致；因 get_register_qr_code_img 只呼叫 domain service、未用到 provider，目前無實際影響，但屬可疑寫法，見 §12。

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

不屬本頁：src/views/auth/ChangePassword.vue（/change-password，未登入態的忘記密碼／強制改密流程，走 CHANGE_PWD_REQ / CHANGE_PWD_BY_REQ）、src/views/auth/OtpVerification.vue（/otp-verify，登入流程 MFA 驗證頁，走 OTP_VERIFY / OTP_RESEND）——兩者常被誤認為本頁一部分，實為獨立 route，見 §12 坑 1。

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：本頁三個外部套件（jedi-auth / jedi-login / jedi-mfa）各自擁有完整 domain/repo 層，主專案 route 幾乎是直接委派、無主專案 app service 包一層（與角色權限管理頁相同模式，見 role-manage.md §8）——改行為前先確認邊界屬哪個套件（CLAUDE.md 外部套件異動規範）。GET /user/<uid> 與 GET /otp-qrcode/<uid> 缺自身限定，新 code 不要比照，兩者都屬已知債（§12）。

9. DB

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

9.2 ER 圖

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

public.users（節錄本頁相關欄位）

public.totp_secrets — TOTP 密鑰真正存放處

public.user_change_pwd_logs — 改密歷史（供重複檢查）

public.user_auth_providers — 第三方登入綁定

public.user_change_password_request（本頁不觸及，列出供對照）

10. 頁面邏輯與資料對應

載入時序：

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

儲存流程：onSaveClick 先跑 v$（基本欄位）驗證，若密碼欄位任一有值再跑 vSecret$ 驗證；通過後組一份完整 payload（含唯讀顯示欄位如 tenants/org_units/user_roles 原樣回送）+ 條件性 password → 單一 PUT /user-profile/<uid>。成功後用 response 更新 userStore 的精簡 userInfo（uid/login_name/nickname/email），並清空密碼欄位與驗證狀態。LDAP／TOTP secret 建立則各自獨立即時呼叫，不等頁面儲存。

錯誤對應：BE error envelope → 由呼叫端 .then/.catch 或全域攔截器轉 toast（本頁未見自訂錯誤文案覆寫，走預設 i18n lang.error.<code>）；常見碼：AUTH_401006（AUTH_UNAUTHORIZED，改到別人的 uid）、AUTH_429001（24 小時內已改過密碼）、AUTH_401009（AUTH_SECRET_SAME_AS_PREVIOUS，近 3 次重複，實際 429）、MFA_401001（MFA_VERIFY_FAILED，本頁未觸發此碼——該碼只在登入流程 /otp-verify 使用）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. MFA 切換改為「驗證後即時生效」（2026-07-09 修，取代原「未驗證即啟用會自鎖」缺陷）：切到 TOTP 時強制走「建立 secret → 顯示 QR Code Dialog → 輸入一次動態碼 → 驗證通過（POST /totp-verify，JWT 自我限定、不發 token）」才允許啟用；Dialog 未驗證關閉即還原開關並提示。切回 Email 即時生效（失敗還原開關）。啟用/停用不再依附基本資料儲存——切換驗證通過即透過 PUT /user-mfa-type（只送 mfa_type 單欄、update 只寫非 None 欄位）立即落 DB（B 案「改了就生效」），不需再按「儲存」；onSaveClick 不再帶 mfa_type。原本即 TOTP 者切他頁再回來免重驗。個人資料頁「帳號安全」已拆成獨立即時生效卡（含 hint-bar）。⚠️ 此行為需 BE + FE 同版部署（舊 FE 直送 totp 對新 BE 會 400）。
2. GET /user/<uid> 無自身限定：僅 @jwt_required()，理論上任何登入者傳他人 uid 都能取得該使用者完整資料（roles/tenants/org_units/mfa_type/auth_providers，已排除 salt/password）。寫入端 PUT /user-profile/<uid> 有擋（401 AUTH_UNAUTHORIZED），讀端沒有——本頁只記錄不修（_overview §5 已知模式）。
3. GET /otp-qrcode/<uid> 完全無 @jwt_required()：本頁所有端點中權限最鬆的一個——未登入也能打，只要知道目標使用者 uid 就能拿到其 TOTP QR Code（等同拿到可掃描綁定的密鑰 URI）。屬安全缺口，收錄僅供追蹤。
4. users.topt_secret 是死欄：DB 有此欄位（text 型別）但主專案、jedi-auth、jedi-mfa 全部程式碼零引用；真正的 TOTP secret 存在獨立表 public.totp_secrets（secret/uri 欄位）。未來若清理孤兒欄位，此欄可列入候選（先走 DROP TABLE 前的四查 SOP）。
5. 改密「新舊密碼相同」錯誤碼已修正（2026-07-08）：原本 AUTH_SECRET_SAME_AS_PREVIOUS 碼寫 AUTH_401009（像 401）卻用 TooManyRequestsError(429) 拋出，碼/型別/語意三重不符；已改為碼 AUTH_400003（移入 400 段）+ BadRequestError(400)，並同步 FE 三語 error-code.json mapping 鍵。AUTH_CHANGE_SECRET_WITHIN_24_HOURS（AUTH_429001，24 小時內限改一次）維持 429 不動。⚠️ 此碼異動需 BE（jedi-auth）+ FE 同版部署。
6. LDAP 綁定 payload 的 user_uid 未驗自身：POST /auth-provider 只檢查 JWT 存在，不比對 user_uid 是否為呼叫者本人；但因綁定必須通過真實 LDAP server 帳密驗證（ldap_adapter.verify_user），實務上攻擊者仍需持有目標帳號在 LDAP 端的有效密碼才能利用，風險低於前兩項讀端點缺口，仍屬待補的權限一致性債。
7. 本頁常與另兩個頁面混淆：/change-password（ChangePassword.vue，未登入態忘記密碼／強制改密，走 CHANGE_PWD_REQ/CHANGE_PWD_BY_REQ）與 /otp-verify（OtpVerification.vue，登入流程 MFA 驗證）都不是本頁的一部分，各自是獨立的 route，行為不要混在一起看。
8. TotpQrcodeRoute MFAService 型別已統一（2026-07-07 已修）：原以 MFAService("email") 建構 TOTP 服務（僅用到 domain service、不呼叫 provider，無實際功能影響），已統一為 MFAService("totp")，與其餘 TOTP 端點一致。
9. 密碼欄位判斷用「兩者任一有值」觸發改密：currSecret.secret || currSecret.confirm_secret 為真才跑密碼驗證並帶入 payload；只填一欄未填另一欄會被 vSecret$ 擋下（兩欄皆 required when 觸發），行為符合預期但錯誤訊息只顯示在未填欄位上，UX 上容易誤解成「另一欄有問題」。
10. PUT payload 回送唯讀顯示欄位：tenants/org_units/user_roles/effective_date/expire_date 這些本頁不可編輯的欄位，儲存時仍原樣組進 payload 一起送出（onSaveClick，UserProfileForm.vue:159-179）。因走的是 update_user 全量欄位覆寫邏輯，若 FE 载入資料與 BE 當前狀態之間有時間差（例如另一個管理員同時改了此使用者的角色），儲存個人資料會意外覆蓋掉那些變更——多人編輯風險，本頁無 socket 提示。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）。
• 測試帳號：任一 dev 環境登入帳號皆可測（測試自己的資料）；憑證見 memory reference_dev_login / .env（不寫入本文件）。
• 導航路徑：登入 → 右上角使用者選單（或直接網址 /user/user-profile，本頁無側邊選單節點，不受 ui_routes 可見性控制）。
• 前置資料：無特殊前置資料；若要測 LDAP 綁定需 system_configs（THIRD_PARTY_LOGIN/LDAP group）已設定且有可連線的 LDAP server。
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；本頁相關 feature 檔以 個人資料 / user-profile / TOTP 搜尋。
• 相關文件：權限系統設計說明書 docs/system-design/permission/；MFA/TOTP 相關套件 jedi-mfa（~/Projects/Jedicogy/module/jedi-python-package/jedi-mfa/）、LDAP 綁定 jedi-login（同路徑下 jedi-login/）。