# 变更提案: admin-frontend-user-management

## 元信息
```yaml
类型: 新功能
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-21
```

---

## 1. 需求

### 背景
当前 `admin-frontend` 已完成登录、主布局与仪表盘，但业务路由仍只有 `/dashboard`。用户本轮明确要求继续沿 [.claude/plan/admin-frontend-login.md](/E:/code/php/Xboard-new/.claude/plan/admin-frontend-login.md) 推进，按照 [apple/DESIGN.md](/E:/code/php/Xboard-new/apple/DESIGN.md) 的 Apple 风格，为后台补齐“用户管理 / 工单管理”入口，且优先完整实现“用户管理”页面。参考图已经给出了目标交互形态，包括左侧菜单分组、用户列表、行内更多操作菜单，以及右侧抽屉式新增/编辑用户表单。

### 目标
- 在管理端新增“用户管理”业务页，完成菜单、路由、页面与真实接口接入。
- 让用户管理页具备可用的搜索、分页、状态展示、更多操作菜单，以及新增/编辑用户抽屉。
- 预留“工单管理”菜单与路由入口，使后台导航结构与参考图对齐，但本轮不展开工单业务实现。

### 约束条件
```yaml
时间约束: 本轮只完整实现“用户管理”，工单管理仅补路由入口和占位页
性能约束: 保持当前轻量 Apple 风格，不新增重型表格或状态管理依赖
兼容性约束: 保持现有 Vue3 + TypeScript + Vite + Element Plus 栈与 hash 路由模式
业务约束: 后端接口沿用现有 `/api/v2/{secure_path}/user/*`、`/plan/fetch`，不改 Laravel API
```

### 验收标准
- [ ] 管理端左侧导航新增“用户管理”分组，包含“用户管理”和“工单管理”两个入口。
- [ ] 用户管理页可通过真实接口完成列表读取、分页、基础筛选、状态/套餐/流量展示。
- [ ] 用户管理页支持新增用户、编辑用户、复制订阅地址、重置密钥、封禁和删除等操作入口，并带明确确认反馈。
- [ ] `admin-frontend` 构建通过，新增页面在桌面和移动端都能正常访问。

---

## 2. 方案

### 技术方案
本轮采用“扩展现有管理壳层 + 新增用户管理业务模块”的方案：

1. 扩展管理端数据层  
   在 `src/types/api.d.ts` 中补充用户、套餐、分页与表单类型；在 `src/api/admin.ts` 中新增用户列表、用户详情、套餐列表、用户创建/更新/重置密钥/封禁/删除等请求封装。

2. 新增用户管理视图  
   在 `src/views/users/` 下拆分页面与抽屉组件。列表页负责搜索、表格、分页、更多操作菜单；抽屉组件负责新增/编辑表单。视觉上延续 Apple 风格的浅灰画布、白色内容区与单一蓝色交互重点。

3. 对齐后端真实创建能力  
   后端 `user/generate` 只能直接创建基础字段（邮箱、密码、套餐、到期时间），无法一次性写入完整表单字段。因此新增用户时采用“两段式”流程：
   - 先调用 `user/generate` 创建基础账号
   - 再按邮箱回查用户 ID，并调用 `user/update` 补齐流量、余额、佣金、权限、限速、设备数、备注等扩展字段

4. 补齐导航与路由  
   将当前仅有仪表盘的侧边栏调整为分组导航，新增 `/users` 路由和 `/tickets` 占位路由；本轮仅实现 `UsersView` 的完整业务功能。

### 影响范围
```yaml
涉及模块:
  - admin-frontend/src/router: 新增用户管理与工单管理路由
  - admin-frontend/src/layouts: 调整侧边栏菜单结构与导航文案
  - admin-frontend/src/api: 扩展用户与套餐相关请求
  - admin-frontend/src/types: 新增用户管理数据类型
  - admin-frontend/src/views/users: 新增用户列表页与表单抽屉
  - admin-frontend/src/views/tickets: 新增工单管理占位页
预计变更文件: 7-9
```

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 后端新增用户接口字段不足，无法一次提交完整表单 | 中 | 前端采用 `generate + fetch + update` 两段式创建流程 |
| 参考图中的“在线设备”字段后端列表接口未直接返回 | 中 | 本轮优先展示可用业务字段，设备相关展示使用已有限制字段和可退化文案 |
| 用户删除属于破坏性操作 | 中 | 在前端增加显式确认和操作完成提示，避免误删 |

---

## 3. 技术设计（可选）

> 涉及路由扩展、API映射与表单编排，需填写。

### 架构设计
```mermaid
flowchart TD
    A[AdminLayout 侧边栏菜单] --> B[UsersView 用户管理页]
    A --> C[TicketsPlaceholderView 工单占位页]
    B --> D[UserToolbar 搜索与操作]
    B --> E[UserTable 列表与更多操作]
    B --> F[UserFormDrawer 新增/编辑抽屉]
    B --> G[admin.ts 用户管理接口]
    F --> G
    G --> H[/user/fetch]
    G --> I[/user/generate]
    G --> J[/user/update]
    G --> K[/user/resetSecret]
    G --> L[/user/ban]
    G --> M[/user/destroy]
    G --> N[/plan/fetch]
```

### API设计
#### ANY /api/v2/{secure_path}/user/fetch
- **请求**: `current`, `pageSize`, `filter[]`, `sort[]`
- **响应**: `{ data: UserListItem[], total: number }`

#### GET /api/v2/{secure_path}/user/getUserInfoById
- **请求**: `id`
- **响应**: 单个用户详情，含邀请人信息

#### POST /api/v2/{secure_path}/user/generate
- **请求**: `email_prefix`, `email_suffix`, `password`, `plan_id`, `expired_at`
- **响应**: `success(true)` 或批量结果

#### POST /api/v2/{secure_path}/user/update
- **请求**: `id` + 用户扩展字段（余额、佣金、流量、权限、限速、设备数、备注等）
- **响应**: `success(true)`

#### GET /api/v2/{secure_path}/plan/fetch
- **请求**: 无
- **响应**: 套餐列表，用于表单选择和表格展示

### 数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| AdminUserListItem | object | 用户列表行数据，包含套餐、邀请人、权限组、流量、状态等 |
| AdminUserFormModel | object | 抽屉表单模型，覆盖新增/编辑时的基础与扩展字段 |
| AdminPlanOption | object | 订阅计划选项，用于表单下拉与列表展示 |
| AdminPaginationResult<T> | object | 用户列表分页结果 |

---

## 4. 核心场景

> 执行完成后同步到对应模块文档

### 场景: 浏览用户列表
**模块**: UsersView
**条件**: 管理员已登录并进入 `/users`
**行为**: 页面读取用户列表、套餐信息并渲染搜索栏、表格、分页
**结果**: 管理员可快速查看用户状态、流量、到期时间与套餐

### 场景: 新增用户
**模块**: UserFormDrawer / admin.ts
**条件**: 管理员在用户管理页点击“创建用户”
**行为**: 管理员填写抽屉表单，前端先生成基础账号，再补写扩展字段
**结果**: 新用户创建成功，列表自动刷新并提示结果

### 场景: 编辑或执行行内操作
**模块**: UsersView / UserFormDrawer
**条件**: 列表中存在目标用户
**行为**: 管理员打开更多菜单执行编辑、复制订阅地址、重置密钥、封禁或删除
**结果**: 对应操作完成并反馈到列表状态

---

## 5. 技术决策

> 本方案涉及的技术决策，归档后成为决策的唯一完整记录

### admin-frontend-user-management#D001: 新增用户采用“两段式创建”以兼容现有后端接口
**日期**: 2026-04-21
**状态**: ✅采纳
**背景**: 参考表单包含余额、佣金、流量、角色、限速、设备数、备注等字段，但后端 `user/generate` 仅支持基础创建字段。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 仅用 `user/generate` 并缩减表单字段 | 实现简单 | 无法对齐参考页字段深度 |
| B: 先 `generate`，再按邮箱回查并 `update` | 能保留完整表单能力 | 前端流程更复杂 |
**决策**: 选择方案 B
**理由**: 既不改后端，也能最大化还原参考抽屉中的管理能力。
**影响**: `admin.ts`、`UsersView`、`UserFormDrawer`

### admin-frontend-user-management#D002: 先补齐用户/工单路由结构，但本轮仅交付完整用户页
**日期**: 2026-04-21
**状态**: ✅采纳
**背景**: 用户要求“添加用户管理、工单管理路由，先完成用户管理”，既要有完整导航结构，又要控制当前实现范围。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 只加用户管理，不处理工单入口 | 实现最小 | 与用户点名的导航结构不一致 |
| B: 同时补齐用户/工单入口，工单先占位 | 与目标结构一致，后续扩展顺滑 | 需要新增一个占位页面 |
**决策**: 选择方案 B
**理由**: 先把信息架构铺平，后续实现工单页时不必再改侧边栏和路由骨架。
**影响**: `router/index.ts`、`layouts/AdminLayout.vue`

---

## 6. 成果设计

> 含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。

### 设计方向
- **美学基调**: Apple Admin Ledger。像 Apple 系统设置和内部运营面板的结合体，用极少的颜色和干净层级承载高密度数据。
- **记忆点**: 浅灰页面基底上嵌入一块大尺寸白色数据工作台，右侧抽屉像系统级面板一样滑入。
- **参考**: 用户提供的用户列表、操作菜单、抽屉表单和侧边栏截图 + [apple/DESIGN.md](/E:/code/php/Xboard-new/apple/DESIGN.md)

### 视觉要素
- **配色**: 背景 `#f5f5f7`、表格/抽屉 `#ffffff`、标题 `#1d1d1f`、强调蓝 `#0071e3`、危险态 `#c93428`
- **字体**: 延续当前系统字体栈 `-apple-system`, `BlinkMacSystemFont`, `SF Pro Display`, `SF Pro Text`, `Helvetica Neue`, Arial, sans-serif`
- **布局**: 页面顶部为标题与操作条，中部为单块白色表格工作区；抽屉从右侧进入，表单按字段组自然分段
- **动效**: 仅保留表格 hover、高亮状态和抽屉进出动画，避免复杂动效
- **氛围**: 轻边框、软阴影、玻璃顶栏，避免深色重装饰和泛滥卡片分割

### 技术约束
- **可访问性**: 所有状态色均保留文字标签；删除、封禁等危险操作必须有二次确认
- **响应式**: 窄屏下工具栏折行、表格横向滚动、抽屉宽度自适应到视口