user-system/docs/plans/ADMIN_FRONTEND_EXECUTION_PLAN.md

Admin 前端唯一执行方案

更新时间：2026-03-19

1. 文档定位

本文是当前唯一有效的 Admin 前端执行方案，后续前端实现、拆分任务、接口联调、验收都以本文为准。

事实来源仅限以下文件：

• docs/API.md
• internal/api/router/router.go
• docs/status/REAL_PROJECT_STATUS.md
• docs/PROJECT_REVIEW_REPORT.md

约束原则：

1. 只实现仓库内已经真实接线、可以联调的 API。
2. PRD 与当前后端实现不一致时，以当前后端事实为准，缺口明确列为延期项或前置依赖。
3. 页面、类型、认证流、API 服务层必须统一，不再允许文档内同时存在 Vue / React、Axios / Fetch、假接口 / 真接口两套口径。

---

2. 当前真实约束

2.1 项目现状

• 仓库中目前没有真实前端项目，Admin 前端尚未开始。
• 后端当前已经通过 go build ./...、go vet ./...、go test ./...。
• 当前项目真实状态是“后端核心链路可用，前端未开始，PRD 仍有未完成范围”。

2.2 必须接受的后端事实

• 用户管理没有 POST /api/v1/users，因此当前不支持“管理员单个创建用户”页面。
• 没有批量启用、批量禁用、批量删除接口，因此不做批量用户操作。
• PUT /api/v1/users/:id/password 当前只允许本人改自己的密码，不支持管理员重置他人密码。
• /api/v1/users/:id/avatar 的处理逻辑实际上只更新当前登录用户头像，因此头像上传只放到“个人中心”，不放到用户管理页。
• 仪表盘统计只提供：
  • 用户总数、各状态人数
  • 今日 / 本周 / 本月新增用户
  • 今日成功 / 失败登录数
  • 本周成功登录数
• 没有系统设置配置接口，因此不做 /settings 页面。
• 没有“当前用户权限快照”接口。前端可稳定获取的是：
  • GET /api/v1/auth/userinfo
  • GET /api/v1/users/:id/roles
• OAuth 回调当前由后端直接返回 JSON，不是标准 SPA redirect 完成态，因此社交登录 / 绑定不纳入当前 MVP。
• 设备接口没有“全局设备列表”，只有：
  • GET /api/v1/devices 当前用户设备
  • GET /api/v1/devices/users/:id 指定用户设备 因此前端不做全局设备管理页面。

---

3. 单一技术栈

当前只接受以下一套前端技术栈：

关注点	统一方案	说明
框架	React 18 + TypeScript	统一组件模型和类型系统
构建工具	Vite	快速启动，适合从零搭建
路由	React Router 6	足够覆盖登录、后台布局、受保护路由
UI 组件	Ant Design 5	后台场景成熟，减少重复造轮子
请求层	浏览器原生 fetch + 自建请求客户端	避免 Axios 二次封装分叉
状态管理	React Context 仅管理会话态	不引入 Redux / Zustand / Pinia
页面数据	页面局部状态 + 受控请求	首版不引入 React Query
表单	Ant Design Form	与 UI 组件一致
样式	CSS Modules + CSS Variables + AntD Theme Token	不引入 styled-components
图表	MVP 不引入额外图表库	当前统计接口不足以支撑复杂图表

明确不采用：

• Vue 3
• Pinia
• Axios
• styled-components
• React Query
• “HTML + CSS + JavaScript 手写管理后台”

3.1 前端技术架构总览

前端统一采用单体 SPA 架构，不拆微前端，不做 SSR，不做多应用并行。

运行时分层固定为：

1. App Shell
   • 应用启动、主题、路由挂载、全局异常边界
2. Session Layer
   • 会话恢复、刷新令牌、登录态广播、路由准入
3. HTTP Client Layer
   • 鉴权头注入、统一解包、401 重试、下载上传
4. Service Layer
   • 按资源拆分 API 方法，不放 UI 逻辑
5. Page / Feature Layer
   • 页面编排、表格、表单、弹窗、抽屉
6. Shared UI Layer
   • 布局、通用表格状态、空态、错误态、确认弹窗

数据流固定为：

Page -> Service -> HTTP Client -> API

禁止反向依赖：

• services 依赖页面组件
• 页面直接拼接 URL 自己发请求
• 多套 token 管理并存
• 多套类型定义并存

3.2 项目目录架构

前端项目统一新建在：

• frontend/admin

目录结构固定为：

frontend/admin/
  package.json
  tsconfig.json
  vite.config.ts
  .env.example
  src/
    app/
      App.tsx
      main.tsx
      router.tsx
      providers/
        AuthProvider.tsx
        ThemeProvider.tsx
    layouts/
      AdminLayout/
      AuthLayout/
    pages/
      auth/
        LoginPage/
        ForgotPasswordPage/
        ResetPasswordPage/
      admin/
        DashboardPage/
        UsersPage/
        RolesPage/
        PermissionsPage/
        LoginLogsPage/
        OperationLogsPage/
        WebhooksPage/
        ImportExportPage/
        ProfilePage/
        ProfileSecurityPage/
    features/
      auth/
      users/
      roles/
      permissions/
      logs/
      webhooks/
      profile/
      import-export/
      devices/
      totp/
    services/
      auth.ts
      users.ts
      roles.ts
      permissions.ts
      stats.ts
      logs.ts
      webhooks.ts
      import-export.ts
      profile.ts
      devices.ts
    lib/
      http/
        client.ts
        auth-session.ts
        errors.ts
      storage/
        token-storage.ts
    components/
      common/
      feedback/
      forms/
    types/
      http.ts
      auth.ts
      user.ts
      role.ts
      permission.ts
      device.ts
      log.ts
      webhook.ts
      stats.ts
    styles/
      tokens.css
      global.css

目录原则：

• pages 只放路由页面，不放复用业务组件
• features 放页面内复用的业务组件与交互逻辑
• services 只放接口调用
• types 只放接口类型与领域类型
• components/common 只放通用 UI，不感知业务资源

3.3 依赖白名单

首版允许引入的前端运行时依赖只保留：

• react
• react-dom
• react-router-dom
• antd
• @ant-design/icons
• dayjs

首版允许引入的开发依赖只保留：

• typescript
• vite
• @vitejs/plugin-react
• eslint
• @types/react
• @types/react-dom
• vitest

依赖准入规则：

1. 没有明确解决当前问题的依赖，不引入。
2. 能用浏览器原生能力解决的问题，不引入包装库。
3. 同类库只保留一套。

3.4 技术简化结论

这版前端技术架构刻意做了收缩，最终结论如下：

• 不做微前端
• 不做 monorepo 拆分
• 不做 SSR / SSG
• 不做 Redux / Zustand / Pinia
• 不做 React Query
• 不做 Axios
• 不做 CSS-in-JS
• 不做图表库优先接入
• 不做权限码驱动的复杂前端元编程

首版只保留四个必须的技术支点：

1. React 页面和路由
2. Context 会话管理
3. fetch 请求客户端
4. Ant Design 后台组件

3.5 工程准则

前端开发时必须遵守以下准则：

1. 一个 API 资源对应一个 service 文件。
2. 一个路由页面对应一个 page 目录。
3. 一个复杂弹窗 / 抽屉对应一个独立 feature 组件。
4. 一个任务只解决一类问题，不混做“页面 + 所有依赖 + 所有接口”。
5. 所有新代码默认 TypeScript 严格模式。
6. 所有请求先写类型，再写 service，再接页面。

---

4. 页面与路由范围

4.1 MVP 页面

路由	访问级别	页面范围	对应 API
/login	公开	账号密码登录、邮箱验证码登录、短信验证码登录	/auth/login /auth/send-email-code /auth/login/email-code /auth/send-code /auth/login/code
/forgot-password	公开	发起密码重置	/auth/forgot-password
/reset-password	公开	校验重置 token、提交新密码	/auth/reset-password
/dashboard	管理员	统计卡片与简表，不做假趋势图	/admin/stats/dashboard /admin/stats/users
/users	管理员	用户列表、筛选、详情抽屉、编辑、状态切换、删除、分配角色	/users /users/:id /users/:id /users/:id/status /users/:id/roles /users/:id
/roles	管理员	角色列表、创建、编辑、删除、启停、分配权限	/roles /roles/:id /roles/:id/status /roles/:id/permissions
/permissions	管理员	权限列表、树、创建、编辑、删除、启停	/permissions /permissions/tree /permissions/:id/status
/logs/login	管理员	登录日志列表	/logs/login
/logs/operation	管理员	操作日志列表	/logs/operation
/webhooks	已登录	Webhook 列表、创建、编辑、删除、投递记录	/webhooks /webhooks/:id/deliveries
/import-export	管理员	导入、导出、模板下载	/admin/users/import /admin/users/export /admin/users/import/template
/profile	已登录	个人资料查看与编辑	/auth/userinfo /users/:id
/profile/security	已登录	修改密码、TOTP、头像上传、本人设备、本人日志	/users/:id/password /auth/2fa/* /users/:id/avatar /devices /logs/login/me /logs/operation/me

4.2 页面能力边界

/users 当前只允许实现：

• 列表分页、关键字筛选、状态筛选、角色筛选、时间筛选、排序
• 查看用户详情
• 编辑用户资料
• 删除用户
• 修改用户状态
• 分配角色

/users 当前明确不做：

• 新建用户
• 批量操作
• 管理员代改他人密码
• 为其他用户上传头像

/dashboard 当前只允许展示真实统计字段，不做以下伪需求：

• 在线用户
• 近 7 / 30 天时序趋势图
• 地域分布图
• 最近注册用户
• 最近登录用户

4.3 延期或阻塞页面

以下页面或功能不进入当前前端实施范围：

• /settings
• 全局 /devices 管理页
• 用户创建页
• 用户批量操作
• 管理员重置他人密码
• “记住我 / 记住设备”
• 社交登录回调页
• 社交账号绑定页
• 依赖权限码的细粒度按钮控制

---

5. 统一类型模型

5.1 基础响应模型

所有请求统一先经过响应解包，禁止页面直接假定不同接口的 data 结构。

export interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}

export interface PaginatedData<T> {
  items: T[];
  total: number;
  page: number;
  page_size: number;
}

注意：

• 分页列表真实格式是 data.items + total + page + page_size。
• 不是所有列表都是分页返回。
• GET /webhooks、GET /users/:id/roles、GET /roles/:id/permissions、GET /permissions/tree 等接口返回的不是 PaginatedData<T>。

5.2 会话与认证类型

export interface SessionUser {
  id: number;
  username: string;
  email: string;
  phone: string;
  nickname: string;
  avatar: string;
  status: 0 | 1 | 2 | 3;
}

export interface TokenBundle {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  user: SessionUser;
}

关键约束：

• POST /auth/login 返回 TokenBundle
• POST /auth/refresh 也返回 TokenBundle
• 不允许再定义“刷新后只返回 access_token”的前端假类型

5.3 领域类型

前端类型定义以当前后端 JSON 字段为准，至少包含以下文件：

• src/types/http.ts
• src/types/auth.ts
• src/types/user.ts
• src/types/role.ts
• src/types/permission.ts
• src/types/device.ts
• src/types/log.ts
• src/types/webhook.ts
• src/types/stats.ts

必须保留的真实枚举约束：

• UserStatus: 0 | 1 | 2 | 3
• RoleStatus: 0 | 1
• PermissionStatus: 0 | 1

---

6. 认证与会话流

6.1 统一会话策略

采用以下单一策略：

1. refresh_token 持久化到 localStorage
2. access_token 保存在内存态
3. 应用启动时优先尝试用 refresh_token 换取新的 TokenBundle
4. 刷新成功后再加载角色信息
5. 刷新失败则清空会话并回到登录页

这样做的原因：

• 当前后端刷新接口已经返回完整 TokenBundle
• 可以避免前端长期持久化过期 access_token
• 页面刷新后可以稳定恢复登录态

6.2 启动流程

应用启动流程固定如下：

1. 读取本地 refresh_token
2. 若存在，则调用 POST /api/v1/auth/refresh
3. 刷新成功后，拿到新的 access_token、refresh_token、user
4. 调用 GET /api/v1/users/{user.id}/roles
5. 从角色列表中推导：
   • roleCodes
   • isAdmin = roleCodes.includes("admin")
6. 会话完成后才渲染受保护路由

补充规则：

• 不以 GET /auth/userinfo 作为唯一启动入口，避免浪费一次可能会被 401 的请求
• GET /auth/userinfo 作为“刷新当前资料”能力保留给 Profile 页面或手动重载

6.3 登录与登出流

登录页支持三种真实入口：

• 账号密码登录
• 邮箱验证码登录
• 短信验证码登录

登录成功后统一执行：

1. 写入新的 refresh_token
2. 将新的 access_token 放入内存
3. 直接使用返回体中的 user
4. 再请求当前用户角色
5. 完成后跳转后台首页

登出统一执行：

1. 调用 POST /api/v1/auth/logout
2. 请求体优先带上当前 access_token 和 refresh_token
3. 无论接口成功与否，都清空本地会话
4. 跳回 /login

6.4 401 处理

请求客户端必须实现单次刷新机制：

1. 普通业务请求收到 401
2. 若当前存在 refresh_token，触发一次全局中的刷新流程
3. 刷新成功后重放原请求
4. 刷新失败则清会话并跳转 /login

禁止旧方案中的以下行为：

• 收到 401 直接跳登录，不尝试刷新
• 刷新后只更新 access_token，不更新 refresh_token

6.5 暂不纳入 MVP 的认证能力

以下能力有 API，但当前不纳入首版登录流：

• 社交登录按钮直连回调完成登录
• 社交账号绑定
• remember me

原因不是“前端不做”，而是“当前后端协议不适合 SPA 稳定落地”。

---

7. API 服务层统一方案

7.1 目录结构

目录结构以 3.2 项目目录架构 为准。

本节只强调 service / lib / types 三层在该目录中的职责：

• lib/http
  • 统一请求客户端、会话刷新、错误模型
• services
  • 资源级 API 访问层
• types
  • 统一接口类型和领域类型

7.2 请求客户端职责

lib/http/client.ts 只做以下事情：

• 拼接基础 URL
• 注入 Authorization: Bearer <access_token>
• 统一解包 ApiResponse<T>
• 统一处理 401
• 统一处理 Blob 下载和 FormData 上传
• 将后端业务错误统一转成前端可消费的 AppError

禁止：

• 页面组件内手写 fetch("/api/v1/...")
• 每个页面自己处理 token 注入与刷新
• 把分页响应和普通响应混成一个类型

7.3 服务层模块边界

services/auth.ts

• loginByPassword
• sendEmailCode
• loginByEmailCode
• sendSmsCode
• loginBySmsCode
• refreshSession
• logout
• forgotPassword
• validateResetToken
• resetPassword
• getUserInfo
• getTwoFactorStatus
• setupTwoFactor
• enableTwoFactor
• disableTwoFactor
• verifyTwoFactor

services/users.ts

• listUsers
• getUser
• updateUser
• deleteUser
• updateUserStatus
• getUserRoles
• assignUserRoles

services/profile.ts

• getMyProfile
• updateMyProfile
• changeMyPassword
• uploadMyAvatar
• getMyLoginLogs
• getMyOperationLogs

services/roles.ts

• listRoles
• createRole
• getRole
• updateRole
• deleteRole
• updateRoleStatus
• getRolePermissions
• assignRolePermissions

services/permissions.ts

• listPermissions
• getPermissionTree
• createPermission
• getPermission
• updatePermission
• deletePermission
• updatePermissionStatus

services/stats.ts

• getDashboardStats
• getUserStats

services/logs.ts

• getLoginLogs
• getOperationLogs

services/webhooks.ts

• listWebhooks
• createWebhook
• updateWebhook
• deleteWebhook
• getWebhookDeliveries

services/import-export.ts

• downloadUserExport
• uploadUserImport
• downloadImportTemplate

services/devices.ts

• getMyDevices
• getUserDevices
• getDevice
• createDevice
• updateDevice
• deleteDevice
• updateDeviceStatus

7.4 下载与上传约束

• 用户导出必须走 Blob 下载
• 导入必须走 multipart/form-data
• 头像上传必须走 multipart/form-data
• 头像上传虽然路径是 /users/:id/avatar，但前端只允许传当前用户 ID

---

8. 权限与路由守卫

8.1 现阶段只做两级守卫

当前前端守卫只做：

• RequireAuth
• RequireAdmin

判断依据：

1. 会话中必须有有效 access_token
2. 启动后必须已成功拉到当前用户角色
3. role.code === "admin" 视为管理员

8.2 当前不做权限码按钮系统

原因：

• 后端没有“当前用户权限快照”公开接口
• 中间件中的 permission_codes 仅存在于服务端请求上下文，不会自动返回给前端

因此当前只允许：

• 管理员页面用 RequireAdmin
• 用户自己的页面按“本人”场景控制

当前不允许：

• 以前端硬编码方式伪造整套按钮级 permission code 控制体系

---

9. 实施阶段与最小任务拆解

9.1 交付顺序

前端按以下顺序交付，不允许跳步：

1. 工程骨架
2. 会话与请求底座
3. 认证页面
4. 管理后台框架
5. 核心管理页
6. 运营与个人安全页
7. 收尾验证

9.2 任务拆解规则

最小任务定义：

• 一个任务只产出一个明确可验证的结果
• 一个任务的完成标准必须能被构建、页面行为或接口联调验证
• 一个任务不能横跨多个资源域

任务粒度控制：

• 基础设施任务：一个文件组或一个运行能力
• 服务层任务：一个资源服务文件
• 页面任务：一个路由页面
• 复杂交互任务：一个弹窗、一个抽屉、一个上传、一个下载流

9.3 M0 工程骨架

ID	任务	产出	完成定义
M0-01	初始化 frontend/admin Vite 项目	基础工程目录	能本地启动空白 React 页面
M0-02	建立 tsconfig 路径别名	@/ 别名	导入路径不再依赖相对路径层层回退
M0-03	建立 .env.example	VITE_API_BASE_URL 规范	请求基地址可配置
M0-04	接入 Ant Design 5 和全局样式	global.css / tokens.css	页面样式正常加载
M0-05	建立 AuthLayout 与 AdminLayout 骨架	两套布局组件	登录页和后台页布局可区分
M0-06	建立应用路由骨架	router.tsx	公开页和受保护页都可访问
M0-07	建立错误页与 404 页	错误反馈页面	未匹配路由可落到 404
M0-08	建立全局 AppError 模型	统一错误结构	页面可接收统一错误对象

9.4 M1 会话与请求底座

ID	任务	产出	完成定义
M1-01	实现 token-storage.ts	刷新令牌读写封装	refresh_token 可稳定存取
M1-02	实现 auth-session.ts	内存态 access token 管理	页内请求可拿到当前 access token
M1-03	实现 client.ts 基础请求能力	GET/POST/PUT/DELETE 封装	页面不再手写原生请求细节
M1-04	实现统一响应解包	ApiResponse<T> 解包	service 可直接返回业务数据
M1-05	实现统一业务错误映射	后端错误转 AppError	页面可稳定提示错误信息
M1-06	实现 401 单次刷新机制	请求重试逻辑	access token 过期后可自动刷新一次
M1-07	实现并发刷新锁	单飞刷新	多请求 401 时只触发一次刷新
M1-08	实现 AuthProvider	全局会话上下文	页面可读取用户、角色、登录状态
M1-09	实现应用启动会话恢复	启动自动 refresh	刷新页面后能恢复登录态
M1-10	实现 RequireAuth	登录守卫	未登录不可进入受保护页面
M1-11	实现 RequireAdmin	管理员守卫	非 admin 不可进入后台管理页
M1-12	定义 http.ts / auth.ts / user.ts 基础类型	通用类型文件	认证和用户请求不再使用 any

9.5 M2 认证页

ID	任务	产出	完成定义
M2-01	实现 services/auth.ts	认证 service	登录、刷新、登出、密码重置接口可调用
M2-02	实现密码登录表单	登录页密码 Tab	可调用 /auth/login 并进入后台
M2-03	实现邮箱验证码发送	邮箱验证码发送流程	可调用 /auth/send-email-code
M2-04	实现邮箱验证码登录表单	邮箱验证码登录 Tab	可调用 /auth/login/email-code
M2-05	实现短信验证码发送	短信验证码发送流程	可调用 /auth/send-code
M2-06	实现短信验证码登录表单	短信验证码登录 Tab	可调用 /auth/login/code
M2-07	实现忘记密码页	ForgotPasswordPage	可调用 /auth/forgot-password
M2-08	实现重置密码页	ResetPasswordPage	可校验并提交重置密码
M2-09	实现登出动作	退出登录入口	退出后会话被清空并跳转登录页
M2-10	实现会话启动加载态	启动屏 / 骨架态	启动恢复期间不闪跳错误页面

9.6 M3 后台框架

ID	任务	产出	完成定义
M3-01	实现后台菜单配置	路由与菜单映射	菜单只出现当前方案允许的页面
M3-02	实现后台头部区域	顶栏组件	能展示当前用户和退出入口
M3-03	实现侧边栏导航	菜单导航	页面间可跳转
M3-04	实现面包屑和页面容器	页面框架组件	后台页面布局一致
M3-05	实现页面级加载 / 空态 / 错误态组件	反馈组件	所有列表页使用统一反馈模式

9.7 M4 Dashboard

ID	任务	产出	完成定义
M4-01	定义 stats.ts 类型	统计类型文件	用户统计和登录统计字段齐全
M4-02	实现 services/stats.ts	统计 service	可请求 dashboard / users stats
M4-03	实现 Dashboard 统计卡片	Dashboard 页面基础版	展示真实统计卡片
M4-04	实现 Dashboard 简表区块	简单文本 / 数字区块	不引入假图表但信息完整

9.8 M5 Users

ID	任务	产出	完成定义
M5-01	完成 user.ts 领域类型	用户列表 / 详情类型	用户页所有字段有类型约束
M5-02	实现 services/users.ts	用户 service	列表、详情、编辑、状态、角色分配可调用
M5-03	实现用户筛选表单	UsersFilter	支持关键字、状态、角色、时间、排序
M5-04	实现用户列表表格	UsersTable	分页和列表展示正常
M5-05	实现用户详情抽屉	UserDetailDrawer	可查看用户详情
M5-06	实现编辑用户抽屉	UserEditDrawer	可提交 /users/:id 更新
M5-07	实现用户状态切换动作	状态更新交互	可提交 /users/:id/status
M5-08	实现用户删除动作	删除确认流	可提交 /users/:id 删除
M5-09	实现用户角色分配弹窗	AssignRolesModal	可提交 /users/:id/roles

9.9 M6 Roles

ID	任务	产出	完成定义
M6-01	定义 role.ts 类型	角色类型文件	列表、详情、权限关联字段齐全
M6-02	实现 services/roles.ts	角色 service	增删改查、启停、权限分配可调用
M6-03	实现角色列表页	RolesPage	列表、分页、状态展示正常
M6-04	实现创建 / 编辑角色弹窗	RoleFormModal	可提交创建和更新
M6-05	实现角色状态切换	状态操作	可提交 /roles/:id/status
M6-06	实现角色删除动作	删除确认流	可删除角色
M6-07	实现角色权限分配弹窗	RolePermissionsModal	可读取并提交角色权限

9.10 M7 Permissions

ID	任务	产出	完成定义
M7-01	定义 permission.ts 类型	权限类型文件	权限树和列表字段齐全
M7-02	实现 services/permissions.ts	权限 service	列表、树、增删改查、启停可调用
M7-03	实现权限列表页	PermissionsPage	列表和树切换正常
M7-04	实现创建 / 编辑权限弹窗	PermissionFormModal	可提交创建和更新
M7-05	实现权限状态切换	状态操作	可提交 /permissions/:id/status
M7-06	实现权限删除动作	删除确认流	可删除权限

9.11 M8 Logs

ID	任务	产出	完成定义
M8-01	定义 log.ts 类型	日志类型文件	登录日志和操作日志字段齐全
M8-02	实现 services/logs.ts	日志 service	登录日志、操作日志接口可调用
M8-03	实现登录日志页	LoginLogsPage	列表、分页、筛选正常
M8-04	实现操作日志页	OperationLogsPage	列表、分页、筛选正常

9.12 M9 Webhooks

ID	任务	产出	完成定义
M9-01	定义 webhook.ts 类型	Webhook 类型文件	列表和投递记录字段齐全
M9-02	实现 services/webhooks.ts	Webhook service	列表、增删改、投递记录可调用
M9-03	实现 Webhook 列表页	WebhooksPage	列表可展示
M9-04	实现创建 / 编辑 Webhook 弹窗	WebhookFormModal	可提交创建和更新
M9-05	实现删除 Webhook 动作	删除确认流	可删除 Webhook
M9-06	实现投递记录抽屉	DeliveriesDrawer	可查看 /webhooks/:id/deliveries

9.13 M10 Import / Export

ID	任务	产出	完成定义
M10-01	实现 services/import-export.ts	导入导出 service	下载模板、上传导入、导出下载可调用
M10-02	实现导出表单	ExportPanel	可设置格式和筛选条件
M10-03	实现导出下载流	Blob 下载	CSV / XLSX 文件可正常下载
M10-04	实现导入上传表单	ImportPanel	可上传 .csv / .xlsx
M10-05	实现模板下载动作	TemplateDownload	可下载导入模板

9.14 M11 Profile / Security

ID	任务	产出	完成定义
M11-01	实现 services/profile.ts	个人中心 service	当前用户资料与安全接口可调用
M11-02	实现 services/devices.ts	设备 service	本人设备接口可调用
M11-03	实现个人资料页	ProfilePage	可查看并编辑个人资料
M11-04	实现修改密码表单	ChangePasswordForm	可提交本人密码修改
M11-05	实现 TOTP 状态与 setup 流程	TOTPSetupPanel	可拉取状态并展示 setup 信息
M11-06	实现 TOTP 启用 / 关闭 / 验证	TOTPActionPanel	可完整跑通 2FA 管理流
M11-07	实现头像上传	AvatarUploadPanel	可上传并刷新当前头像
M11-08	实现本人设备列表	MyDevicesPanel	可展示和操作 /devices
M11-09	实现本人登录日志	MyLoginLogsPanel	可展示 /logs/login/me
M11-10	实现本人操作日志	MyOperationLogsPanel	可展示 /logs/operation/me

9.15 M12 收尾与验证

ID	任务	产出	完成定义
M12-01	统一菜单权限与路由准入复核	菜单守卫检查	管理页不会暴露给非 admin
M12-02	统一分页交互复核	分页行为检查	所有分页页都按真实结构工作
M12-03	统一错误提示与空态复核	反馈体验检查	页面失败时不出现白屏
M12-04	添加关键基础测试	vitest 用例	至少覆盖请求客户端和会话恢复逻辑
M12-05	执行前端构建验证	npm run build	生产构建通过
M12-06	执行联调烟雾验证	手工联调清单	每个已纳入页面至少完成一次真实接口验证

9.16 当前不拆解的延期项

以下项在后端前置条件未补齐前，不进入任务拆解：

• 社交登录 / 绑定
• 系统设置
• 全局设备管理
• 用户创建
• 批量操作
• 细粒度权限码前端控制
• 富图表仪表盘

---

10. 后端补齐前置依赖

以下接口或协议补齐后，前端范围才能继续扩张：

1. POST /api/v1/users，用于管理员单个创建用户
2. 用户批量操作接口
3. 当前用户角色码 / 权限码快照接口
4. SPA 友好的 OAuth callback redirect 协议
5. 社交账号绑定握手协议，而不是直接要求前端提交 open_id
6. 系统设置读写接口
7. 全局设备列表与检索接口
8. 时间序列统计、最近活动、地域分布等仪表盘接口

---

11. 验收基线

后续前端实现必须满足以下验收条件：

1. 每个页面都能映射到当前真实后端 API，不出现“文档有、后端无”的按钮。
2. 所有分页页都按真实结构处理 items / total / page / page_size。
3. 刷新会话必须轮换 refresh_token，不能只更新 access_token。
4. Admin 页面必须以当前用户角色中的 admin 作为准入条件。
5. 个人头像上传只能从个人中心进入，不能放进用户管理页。
6. Dashboard 只展示当前统计接口真实提供的数据。
7. 不新增任何与本文冲突的前端栈或页面规划文档。