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

frontend-admin/src/api/mfa.ts

@@ -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
+}

frontend-admin/src/router/index.ts

@@ -126,6 +126,13 @@ const routes = [
         component: () => import('@/views/Placeholder.vue'),
         meta: { title: '知识库管理', requiresAuth: true, comingSoon: true },
       },
+      {
+        // Phase 2.4 task #20 — MFA 管理(管理员重置员工 MFA 绑定)
+        path: 'mfa-manage',
+        name: 'MfaManage',
+        component: () => import('@/views/MfaManage.vue'),
+        meta: { title: 'MFA 管理', requiresAuth: true },
+      },
     ],
   },
   {

frontend-admin/src/views/MfaManage.vue

@@ -0,0 +1,403 @@
+<!--
+=============================================================================
+企微IT智能服务台 — MFA 管理页 (Phase 2.4, task #20)
+=============================================================================
+说明:管理员管理所有用户 MFA 绑定的页面
+
+  功能:
+    - 表格列出所有用户的 MFA 状态(已绑/未绑)
+    - 搜索(姓名/employee_id)+ 过滤(已绑/未绑/全部)+ 分页
+    - "重置 MFA" 按钮 → 调 POST /api/admin/mfa/reset/{employee_id}
+      (无 OTP 验证,管理员特权,用于员工丢手机兜底)
+    - 重置前 ElMessageBox 二次确认(防误操作)
+
+  设计要点:
+    - 不在表格里直接显示 secret(安全考虑)
+    - 状态列用 el-tag 颜色区分:已绑=success,未绑=info
+    - 重置按钮在已绑行才显示(未绑无需重置)
+    - "最近验证时间"列给管理员做审计参考
+-->
+<template>
+  <div class="mfa-manage-page">
+    <!-- 页面标题 -->
+    <div class="page-header">
+      <div>
+        <div class="page-title">MFA 管理</div>
+        <div class="page-desc">管理所有用户的动态令牌(MFA)绑定状态,丢手机兜底重置</div>
+      </div>
+    </div>
+
+    <!-- ============================================================ -->
+    <!-- 筛选栏 -->
+    <!-- ============================================================ -->
+    <div class="filter-bar">
+      <el-input
+        v-model="filters.keyword"
+        placeholder="搜索员工姓名 / Employee ID"
+        :prefix-icon="Search"
+        clearable
+        style="width: 260px"
+        @keyup.enter="handleSearch"
+      />
+      <el-select v-model="filters.bound" placeholder="绑定状态" clearable style="width: 140px">
+        <el-option label="全部" value="" />
+        <el-option label="已绑定" value="true" />
+        <el-option label="未绑定" value="false" />
+      </el-select>
+      <el-button type="primary" :icon="Search" @click="handleSearch">搜索</el-button>
+      <el-button :icon="Refresh" @click="handleReset">重置</el-button>
+      <el-button :icon="Refresh" @click="loadUsers">刷新</el-button>
+    </div>
+
+    <!-- ============================================================ -->
+    <!-- 统计卡片 -->
+    <!-- ============================================================ -->
+    <div class="stat-cards">
+      <div class="stat-card">
+        <div class="stat-label">总用户数</div>
+        <div class="stat-value">{{ pagination.total }}</div>
+      </div>
+      <div class="stat-card stat-card--success">
+        <div class="stat-label">已绑定</div>
+        <div class="stat-value">{{ boundCount }}</div>
+      </div>
+      <div class="stat-card stat-card--info">
+        <div class="stat-label">未绑定</div>
+        <div class="stat-value">{{ unboundCount }}</div>
+      </div>
+    </div>
+
+    <!-- ============================================================ -->
+    <!-- 用户 MFA 状态表格 -->
+    <!-- ============================================================ -->
+    <div class="data-table-wrapper">
+      <el-table
+        :data="users"
+        v-loading="loading"
+        stripe
+        size="small"
+        empty-text="暂无用户记录"
+      >
+        <el-table-column prop="employee_id" label="Employee ID" min-width="140" />
+        <el-table-column prop="name" label="姓名" min-width="100">
+          <template #default="{ row }">
+            <span v-if="row.name">{{ row.name }}</span>
+            <span v-else class="text-muted">—</span>
+          </template>
+        </el-table-column>
+        <el-table-column prop="roles" label="角色" min-width="120">
+          <template #default="{ row }">
+            <el-tag
+              v-for="role in (row.roles || [])"
+              :key="role"
+              size="small"
+              :type="getRoleTagType(role)"
+              class="role-tag"
+            >
+              {{ role }}
+            </el-tag>
+            <span v-if="!row.roles || row.roles.length === 0" class="text-muted">—</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="MFA 状态" min-width="100">
+          <template #default="{ row }">
+            <el-tag :type="row.bound ? 'success' : 'info'" size="small">
+              {{ row.bound ? '已绑定' : '未绑定' }}
+            </el-tag>
+          </template>
+        </el-table-column>
+        <el-table-column prop="bound_at" label="首次绑定时间" min-width="160">
+          <template #default="{ row }">
+            <span v-if="row.bound_at">{{ formatTime(row.bound_at) }}</span>
+            <span v-else class="text-muted">—</span>
+          </template>
+        </el-table-column>
+        <el-table-column prop="last_verified_at" label="最近验证时间" min-width="160">
+          <template #default="{ row }">
+            <span v-if="row.last_verified_at">{{ formatTime(row.last_verified_at) }}</span>
+            <span v-else class="text-muted">—</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="操作" width="140" fixed="right">
+          <template #default="{ row }">
+            <el-button
+              v-if="row.bound"
+              type="danger"
+              size="small"
+              link
+              :disabled="resettingId === row.employee_id"
+              @click="handleResetMfa(row)"
+            >
+              {{ resettingId === row.employee_id ? '重置中...' : '重置 MFA' }}
+            </el-button>
+            <span v-else class="text-muted">无需操作</span>
+          </template>
+        </el-table-column>
+      </el-table>
+    </div>
+
+    <!-- ============================================================ -->
+    <!-- 分页 -->
+    <!-- ============================================================ -->
+    <div class="pagination-bar">
+      <el-pagination
+        v-model:current-page="pagination.page"
+        v-model:page-size="pagination.pageSize"
+        :total="pagination.total"
+        :page-sizes="[10, 20, 50, 100]"
+        layout="total, sizes, prev, pager, next, jumper"
+        @current-change="loadUsers"
+        @size-change="handleSizeChange"
+      />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+// ============================================================================
+// 依赖导入
+// ============================================================================
+import { ref, reactive, computed, onMounted } from 'vue'
+import { Search, Refresh } from '@element-plus/icons-vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { listMfaUsers, resetMfa } from '@/api/mfa'
+import type { MfaUserStatus } from '@/api/mfa'
+
+// ============================================================================
+// 状态
+// ============================================================================
+const loading = ref<boolean>(false)
+const users = ref<MfaUserStatus[]>([])
+const resettingId = ref<string>('')  // 正在重置的 employee_id(给按钮 loading 用)
+
+const filters = reactive({
+  keyword: '',
+  bound: '' as '' | 'true' | 'false',
+})
+
+const pagination = reactive({
+  page: 1,
+  pageSize: 20,
+  total: 0,
+})
+
+// ============================================================================
+// 计算:已绑/未绑数量(基于当前页数据)
+// ============================================================================
+const boundCount = computed<number>(() =>
+  users.value.filter((u) => u.bound).length
+)
+const unboundCount = computed<number>(() =>
+  users.value.filter((u) => !u.bound).length
+)
+
+// ============================================================================
+// 数据加载
+// ============================================================================
+async function loadUsers(): Promise<void> {
+  loading.value = true
+  try {
+    const params: {
+      keyword?: string
+      bound?: '' | 'true' | 'false'
+      page: number
+      page_size: number
+    } = {
+      page: pagination.page,
+      page_size: pagination.pageSize,
+    }
+    if (filters.keyword.trim()) params.keyword = filters.keyword.trim()
+    if (filters.bound) params.bound = filters.bound
+
+    const data = await listMfaUsers(params)
+    users.value = data.items || []
+    pagination.total = data.total || 0
+  } catch (err: any) {
+    // 静默失败,使用空数据
+    users.value = []
+    pagination.total = 0
+    const msg = err?.response?.data?.message || err?.message || '加载用户 MFA 列表失败'
+    ElMessage.error(msg)
+  } finally {
+    loading.value = false
+  }
+}
+
+// ============================================================================
+// 事件处理
+// ============================================================================
+function handleSearch(): void {
+  pagination.page = 1
+  loadUsers()
+}
+
+function handleReset(): void {
+  filters.keyword = ''
+  filters.bound = ''
+  pagination.page = 1
+  loadUsers()
+}
+
+function handleSizeChange(): void {
+  pagination.page = 1
+  loadUsers()
+}
+
+/**
+ * 重置指定用户的 MFA
+ * 二次确认 → 调 API → 刷新列表
+ */
+async function handleResetMfa(row: MfaUserStatus): Promise<void> {
+  const name = row.name || row.employee_id
+  try {
+    await ElMessageBox.confirm(
+      `确认重置 ${name} 的 MFA 绑定?\n\n重置后该用户需要重新绑定才能使用 MFA 功能(用于员工丢手机兜底)。\n此操作不可恢复,请谨慎操作。`,
+      '重置 MFA 确认',
+      {
+        type: 'warning',
+        confirmButtonText: '确认重置',
+        cancelButtonText: '取消',
+        confirmButtonClass: 'el-button--danger',
+      }
+    )
+  } catch {
+    // 用户取消
+    return
+  }
+
+  resettingId.value = row.employee_id
+  try {
+    await resetMfa(row.employee_id)
+    ElMessage.success(`已重置 ${name} 的 MFA 绑定`)
+    // 刷新当前页
+    await loadUsers()
+  } catch (err: any) {
+    const msg = err?.response?.data?.message || err?.message || '重置失败'
+    ElMessage.error(msg)
+  } finally {
+    resettingId.value = ''
+  }
+}
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+function formatTime(iso: string | null | undefined): string {
+  if (!iso) return '—'
+  const d = new Date(iso)
+  if (isNaN(d.getTime())) return iso
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+function getRoleTagType(role: string): 'success' | 'warning' | 'danger' | 'info' {
+  const map: Record<string, 'success' | 'warning' | 'danger' | 'info'> = {
+    user: 'info',
+    agent: 'success',
+    admin: 'danger',
+  }
+  return map[role] || 'info'
+}
+
+// ============================================================================
+// 生命周期
+// ============================================================================
+onMounted(() => {
+  loadUsers()
+})
+</script>
+
+<style scoped>
+.mfa-manage-page {
+  /* 页面容器 */
+}
+
+.page-header {
+  margin-bottom: 20px;
+}
+
+.page-title {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin-bottom: 4px;
+}
+
+.page-desc {
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+/* 筛选栏 */
+.filter-bar {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  margin-bottom: 16px;
+}
+
+/* 统计卡片 */
+.stat-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 12px;
+  margin-bottom: 20px;
+}
+
+.stat-card {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 16px 20px;
+  transition: border-color 0.2s;
+}
+
+.stat-card:hover {
+  border-color: var(--border-hover);
+}
+
+.stat-card--success {
+  border-left: 3px solid var(--success);
+}
+
+.stat-card--info {
+  border-left: 3px solid var(--text-muted);
+}
+
+.stat-label {
+  font-size: 12px;
+  color: var(--text-muted);
+  margin-bottom: 6px;
+}
+
+.stat-value {
+  font-size: 22px;
+  font-weight: 600;
+  color: var(--text-primary);
+  line-height: 1.2;
+}
+
+/* 数据表格 */
+.data-table-wrapper {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+  margin-bottom: 16px;
+}
+
+.role-tag {
+  margin-right: 4px;
+}
+
+.text-muted {
+  color: var(--text-muted);
+  font-size: 12px;
+}
+
+/* 分页 */
+.pagination-bar {
+  display: flex;
+  justify-content: flex-end;
+}
+</style>