feat(mfa-ui): 前端 MFA UI - 绑定+验证+高危弹窗+管理 (Phase 2.4 task #20)

2026-06-21 01:16:36 +08:00
parent c1ac9b936c
commit f564d0e42a
7 changed files with 1484 additions and 0 deletions
@@ -0,0 +1,111 @@
+// =============================================================================
+// 企微IT智能服务台 — 管理后台 MFA 管理 API 适配层 (Phase 2.4)
+// =============================================================================
+// 说明:封装 /api/admin/mfa/* 管理员视角的端点
+// 对应后端: backend/app/api/mfa.py (Phase 2.1, task #17) admin_router 部分
+//
+// 管理员端点:
+//   GET  /api/admin/mfa/users                 — 列出所有用户 MFA 状态
+//   POST /api/admin/mfa/reset/{employee_id}   — 重置指定用户 MFA(丢手机兜底)
+//
+// 用户视角的 5 个端点(/api/mfa/*)由 frontend-agent 端 mfa.ts 封装
+// 管理后台如需代理用户操作(管理员自己绑定)也可引用 frontend-agent 的 API
+//
+// 鉴权:
+//   - 全部用 require_role("admin")(管理员)
+//   - 响应格式: {code: 0, data: {}, message: "success"}  业务码 0 表示成功
+//
+// 典型管理员场景:
+//   1. 进入 /mfa-manage → 调 GET /api/admin/mfa/users → 表格展示
+//   2. 搜索 + 过滤 + 分页(支持按 bound/姓名/employee_id)
+//   3. 点"重置 MFA" → 调 POST /api/admin/mfa/reset/{employee_id}
+//   4. 弹 ElMessageBox 二次确认(防误操作) → 调重置端点
+// =============================================================================
+
+import apiClient from './index'
+import type { AxiosResponse } from 'axios'
+
+// --------------------------------------------------------------------------
+// TypeScript 类型定义
+// --------------------------------------------------------------------------
+
+/** 单个用户的 MFA 状态条目 */
+export interface MfaUserStatus {
+  /** 员工 ID(企微 userid) */
+  employee_id: string
+  /** 员工姓名 */
+  name?: string
+  /** 角色列表 */
+  roles?: string[]
+  /** 是否已绑定 MFA */
+  bound: boolean
+  /** 是否已启用 MFA(与 bound 等价) */
+  enabled: boolean
+  /** 首次绑定时间(ISO 8601,可空) */
+  bound_at?: string | null
+  /** 最近一次验证成功时间(ISO 8601,可空) */
+  last_verified_at?: string | null
+}
+
+/** GET /api/admin/mfa/users 响应 */
+export interface MfaUserListData {
+  /** 用户 MFA 状态列表 */
+  items: MfaUserStatus[]
+  /** 总数 */
+  total: number
+  /** 当前页码 */
+  page: number
+  /** 每页大小 */
+  page_size: number
+}
+
+/** GET /api/admin/mfa/users 查询参数 */
+export interface MfaUserListParams {
+  /** 按姓名或 employee_id 模糊搜索 */
+  keyword?: string
+  /** 过滤绑定状态(空/true/false) */
+  bound?: '' | 'true' | 'false'
+  /** 页码(从 1 开始) */
+  page?: number
+  /** 每页大小 */
+  page_size?: number
+}
+
+/** POST /api/admin/mfa/reset/{employee_id} 响应 */
+export interface MfaAdminResetData {
+  /** 重置是否成功 */
+  success: boolean
+}
+
+// --------------------------------------------------------------------------
+// API 函数
+// --------------------------------------------------------------------------
+
+/**
+ * 1) 列出所有用户的 MFA 状态(支持搜索 + 过滤 + 分页)
+ * 管理员在 /mfa-manage 页面调这个
+ *
+ * @param params 查询参数
+ * @returns 分页数据
+ */
+export async function listMfaUsers(
+  params: MfaUserListParams = {}
+): Promise<MfaUserListData> {
+  const response: AxiosResponse = await apiClient.get('/admin/mfa/users', { params })
+  return response.data.data
+}
+
+/**
+ * 2) 重置指定员工的 MFA 绑定(管理员特权,无 OTP 验证)
+ * 使用场景:
+ *   - 员工丢手机/换手机 → 管理员在后台"重置 MFA"按钮
+ *
+ * @param employeeId 员工 ID(企微 userid)
+ * @returns 重置结果
+ */
+export async function resetMfa(employeeId: string): Promise<MfaAdminResetData> {
+  const response: AxiosResponse = await apiClient.post(
+    `/admin/mfa/reset/${encodeURIComponent(employeeId)}`
+  )
+  return response.data.data
+}