# 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`

目录结构固定为：

```text
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` 结构。

```ts
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 会话与认证类型

```ts
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. 不新增任何与本文冲突的前端栈或页面规划文档。