用户管理系统设计文档

概述

用户管理系统是后台管理系统的核心模块之一，专为超级管理员设计，提供用户信息查看、用户角色管理、用户状态管理等功能。系统采用 Vue3 + Element Plus + TypeScript 技术栈开发，确保类型安全和良好的用户体验。

核心功能

1. 用户列表管理

• 用户列表展示（分页）
• 按用户名搜索
• 用户信息展示（ID、用户名、邮箱、手机号、角色、状态、验证状态、最后登录时间、注册时间）

2. 用户角色管理

• 查看用户当前角色
• 修改用户角色（支持 guest、normal、vip、svip、admin）
• 角色修改权限验证（不能将用户设置为超级管理员，不能将超级管理员设置为其他角色）

3. 用户状态管理

• 查看用户当前状态
• 修改用户状态（active-激活、inactive-禁用、locked-锁定）
• 状态修改权限验证（不能修改超级管理员的状态）
• 修改前确认提示

权限控制

访问权限

• 仅超级管理员可访问：用户管理功能需要超级管理员权限
• 路由级别权限控制：通过 requireAuth: [ROLE_SUPER_ADMIN] 配置
• 后端接口权限控制：所有用户管理接口都需要超级管理员权限验证

操作权限

• 用户角色修改：仅超级管理员可修改用户角色，且不能将用户设置为超级管理员，也不能将超级管理员设置为其他角色
• 用户状态修改：仅超级管理员可修改用户状态，且不能修改超级管理员的状态

数据库设计

用户管理系统主要使用以下数据表：

1. user（用户表）

存储用户的基本信息。

主要字段：

• id: 主键，自增
• username: 用户名（唯一）
• email: 邮箱（唯一，可为空）
• phone: 手机号（唯一，可为空）
• email_verified: 邮箱是否已验证（boolean）
• phone_verified: 手机号是否已验证（boolean）
• role_id: 角色ID（关联role表）
• status: 用户状态（enum: active-激活, inactive-禁用, locked-锁定）
• last_login_ip: 最后登录IP
• last_login_time: 最后登录时间
• created_at: 创建时间
• updated_at: 更新时间

详细字段说明请参考 数据库设计文档。

2. role（角色表）

存储系统角色信息。

主要字段：

• id: 主键，自增
• key: 角色标识（唯一，如：super_admin、admin、svip、vip、normal、guest）
• name: 角色名称（如：超级管理员、管理员、贵宾会员、会员用户、普通用户、游客）
• status: 角色状态
• description: 角色描述

业务流程

1. 查看用户列表

1. 超级管理员登录后台管理系统
2. 点击"用户管理"或从仪表盘进入
3. 系统显示用户列表（分页）
4. 可输入用户名进行搜索
5. 系统返回匹配的用户列表

2. 修改用户角色

1. 在用户列表中点击"修改角色"
2. 弹出角色修改对话框
3. 显示当前角色信息
4. 选择新角色（guest、normal、vip、svip、admin）
5. 点击"确认修改"
6. 系统验证权限（不能将用户设置为超级管理员）
7. 更新用户角色
8. 刷新用户列表

3. 修改用户状态

1. 在用户列表中点击"修改状态"
2. 弹出状态修改对话框
3. 显示当前状态信息
4. 选择新状态（active、inactive、locked）
5. 点击"确认修改"
6. 系统弹出确认提示
7. 用户确认后，系统验证权限（不能修改超级管理员状态）
8. 更新用户状态
9. 刷新用户列表

主要涉及文件

后端文件

路由层

• src/routes/users.mts：用户相关路由

  • GET /users/users：查询用户列表（分页）
  • POST /users/update-role：更新用户角色
  • POST /users/update-status：更新用户状态

• src/routes/role.mts：角色相关路由

  • GET /role/roles：查询所有角色

控制器层

• src/controllers/user.mts：用户相关控制器
  • queryUserListPage：查询用户列表（分页）
  • cUpdateUserRole：更新用户角色
  • cUpdateUserStatus：更新用户状态

服务层

• src/services/user.mts：用户相关业务逻辑
  • getUserInfo：获取用户信息
  • transformUserInfo：转换用户信息格式

数据模型层

• src/models/User.mts：用户表模型定义

前端文件

管理后台（apps/admin/）

• apps/admin/src/views/UsersView/UsersView.vue：用户管理页面
  • 用户列表展示
  • 搜索功能
  • 修改角色对话框
  • 修改状态对话框
  • 分页功能

API 接口

• apps/admin/src/api/users.ts：用户相关API
  • apiGetUserList：查询用户列表
  • apiGetRoleList：查询角色列表
  • apiUpdateUserRole：更新用户角色
  • apiUpdateUserStatus：更新用户状态

路由配置

• apps/admin/src/router/index.ts：管理后台路由配置
  • /users：用户管理路由（需要超级管理员权限）

类型定义

• typings/user.d.ts：用户相关类型定义

  • User：用户类型
  • UserWithRole：带角色信息的用户类型
  • UserInfo：用户信息类型（用于前端展示）
  • API相关类型定义

• apps/admin/src/api/users.ts：前端用户相关类型定义

  • User：前端用户类型
  • Role：角色类型
  • API参数和返回值类型

API 接口

用户管理相关接口

获取用户列表

• 路径：GET /api/users/users
• 权限：超级管理员
• 参数：
  • pageNo（可选）：页码，默认1
  • pageSize（可选）：每页数量，默认10
  • name（可选）：用户名（模糊搜索）
• 响应：

  {
    list: UserInfo[],
    total: number
  }

获取角色列表

• 路径：GET /api/role/roles
• 权限：登录用户
• 响应：

  Role[]

更新用户角色

• 路径：POST /api/users/update-role
• 权限：超级管理员
• 请求体：

  {
    userId: number,
    role: "guest" | "normal" | "vip" | "svip" | "admin" | "super_admin"
  }

• 限制：
  • 不能将用户设置为超级管理员
  • 不能将超级管理员设置为其他角色

更新用户状态

• 路径：POST /api/users/update-status
• 权限：超级管理员
• 请求体：

  {
    userId: number,
    status: "active" | "inactive" | "locked"
  }

• 限制：
  • 不能修改超级管理员的状态

安全考虑

1. 权限验证

• 所有用户管理接口都需要进行权限验证
• 前端路由通过 requireAuth 配置权限要求
• 后端接口通过 authMiddleware 中间件验证权限

2. 操作限制

• 超级管理员角色和状态不能被修改
• 不能通过接口将普通用户设置为超级管理员
• 所有敏感操作都有确认提示

3. 数据安全

• 用户密码不会返回给前端
• 敏感信息（如IP地址）仅管理员可见
• 所有操作都有日志记录

扩展建议

功能扩展

1. 用户详情页：查看用户的详细信息、操作日志等
2. 批量操作：支持批量修改用户角色或状态
3. 用户导入导出：支持Excel导入导出用户数据
4. 操作日志：记录管理员的所有操作，便于审计
5. 权限管理：更细粒度的权限控制（如仅允许修改特定角色的用户）
6. 用户搜索增强：支持按邮箱、手机号、角色、状态等多条件搜索

性能优化

1. 列表缓存：对用户列表进行缓存，减少数据库查询
2. 分页优化：使用游标分页替代偏移分页，提高大数据量下的性能
3. 搜索优化：使用全文索引优化用户名搜索