Xboard/.helloagents/archive/2026-04/202604210441_admin-frontend-user-management/proposal.md

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

元信息

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

---

1. 需求

背景

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

目标

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

约束条件

时间约束: 本轮只完整实现“用户管理”，工单管理仅补路由入口和占位页
性能约束: 保持当前轻量 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 的完整业务功能。

影响范围

涉及模块:
  - 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映射与表单编排，需填写。

架构设计

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

视觉要素

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

技术约束

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