audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6fab4a86d4e5be49a3cedf265b199aac5c737eae
dashboard/.qoder/repowiki/zh/content/后端API文档/用户管理API.md
T
eafonyang 08da279275 新增项目文档
2026-06-30 14:46:52 +08:00

18 KiB
Raw Blame History

用户管理API

**本文档引用的文件** - [backend/src/routes/users.js](file://backend/src/routes/users.js) - [backend/src/models/DashboardUser.js](file://backend/src/models/DashboardUser.js) - [backend/src/middleware/auth.js](file://backend/src/middleware/auth.js) - [backend/src/utils/password.js](file://backend/src/utils/password.js) - [backend/src/utils/response.js](file://backend/src/utils/response.js) - [backend/src/routes/auth.js](file://backend/src/routes/auth.js) - [backend/src/utils/jwt.js](file://backend/src/utils/jwt.js) - [backend/src/services/userBootstrap.js](file://backend/src/services/userBootstrap.js) - [backend/src/app.js](file://backend/src/app.js) - [frontend/src/api/user.js](file://frontend/src/api/user.js) - [frontend/src/views/system/users/index.vue](file://frontend/src/views/system/users/index.vue)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介

本文件为系统“用户管理API”的详细RESTful接口文档，覆盖用户CRUD操作（列表查询、详情获取、创建、更新、删除）、权限控制与角色管理、状态控制、密码重置、账户激活以及批量操作与导入导出的实现指南。文档同时提供前后端交互流程图与最佳实践建议，帮助开发者快速集成与维护。

项目结构

后端采用Express + Sequelize架构，前端基于Vue3 + Element Plus。用户管理API位于独立路由模块中，并通过认证中间件进行统一鉴权。

graph TB
subgraph "后端"
A["应用入口<br/>backend/src/app.js"]
B["路由汇总<br/>backend/src/routes/index.js"]
C["用户路由<br/>backend/src/routes/users.js"]
D["认证中间件<br/>backend/src/middleware/auth.js"]
E["用户模型<br/>backend/src/models/DashboardUser.js"]
F["密码工具<br/>backend/src/utils/password.js"]
G["响应封装<br/>backend/src/utils/response.js"]
H["认证路由<br/>backend/src/routes/auth.js"]
I["JWT 工具<br/>backend/src/utils/jwt.js"]
J["引导服务<br/>backend/src/services/userBootstrap.js"]
end
subgraph "前端"
K["用户API封装<br/>frontend/src/api/user.js"]
L["用户管理页面<br/>frontend/src/views/system/users/index.vue"]
end
A --> B --> C
C --> D
C --> E
C --> F
C --> G
H --> I
H --> F
J --> E
K --> C
L --> K

图表来源

章节来源

核心组件

  • 用户路由模块：提供用户CRUD接口，内置分页、模糊查询、状态与角色变更校验。
  • 认证中间件：统一处理Bearer Token解析与超级管理员权限校验。
  • 密码工具：PBKDF2哈希与校验，确保密码安全存储。
  • 响应封装：统一封装成功/错误/无数据返回格式。
  • 用户模型：定义字段类型、默认值与注释，支撑权限与状态控制。
  • 引导服务：首次部署自动创建超级管理员账号。

章节来源

架构总览

用户管理API遵循“路由-中间件-模型-工具”分层设计，所有用户管理接口均需通过认证中间件并具备超级管理员权限。

sequenceDiagram
participant FE as "前端"
participant API as "用户路由(users.js)"
participant AUTH as "认证中间件(auth.js)"
participant MODEL as "用户模型(DashboardUser)"
participant PWD as "密码工具(password.js)"
participant RESP as "响应封装(response.js)"
FE->>API : "调用受保护的用户管理接口"
API->>AUTH : "执行鉴权与超级管理员校验"
AUTH-->>API : "通过后注入用户上下文"
API->>MODEL : "读写数据库"
API->>PWD : "密码哈希/校验"
API->>RESP : "封装统一响应"
API-->>FE : "返回JSON响应"

图表来源

详细组件分析

接口清单与规范

  • 基础路径：/api/users
  • 认证方式：Authorization: Bearer
  • 权限要求：仅超级管理员可访问
  • 分页参数：skip（起始偏移），limit（最大1000，默认100）
  • 查询参数：username（模糊匹配）

章节来源

列表查询

  • 方法：GET
  • 路径：/api/users/
  • 请求参数：
    • skip：数字，可选
    • limit：数字，范围[1,1000]，默认100
    • username：字符串，模糊查询用户名
  • 成功响应：包含items、total、skip、limit的分页对象
  • 错误响应：空数据时返回“无数据”标识
sequenceDiagram
participant FE as "前端"
participant API as "GET /api/users/"
participant MODEL as "DashboardUser"
participant RESP as "ApiResponse"
FE->>API : "携带分页与查询参数"
API->>MODEL : "统计总数与分页查询"
MODEL-->>API : "返回用户列表"
API->>RESP : "封装分页结果"
API-->>FE : "返回统一响应"

图表来源

章节来源

创建用户

  • 方法：POST
  • 路径：/api/users/
  • 请求体字段：
    • username：字符串，必填，长度<=64
    • password：字符串，必填，长度>=6
    • is_super_admin：布尔，可选，默认false
  • 成功响应：返回创建的用户字典
  • 限制：
    • 用户名唯一
    • 至少保留一个超级管理员（删除/降级时校验）
flowchart TD
Start(["开始"]) --> Validate["校验用户名与密码长度"]
Validate --> Exists{"用户名已存在？"}
Exists --> |是| ErrExists["返回错误：用户名已存在"]
Exists --> |否| Hash["生成密码哈希"]
Hash --> Create["创建用户记录"]
Create --> Log["记录日志"]
Log --> Done(["结束"])
ErrExists --> Done

图表来源

章节来源

更新用户

  • 方法：PUT
  • 路径：/api/users/:user_id
  • 请求体字段：
    • status：0或1，可选
    • is_super_admin：布尔，可选
    • password：字符串，可选（若提供则长度>=6）
  • 成功响应：返回更新后的用户字典
  • 限制：
    • 不能禁用或降级最后一个超级管理员
    • 当前登录用户不可自我删除
flowchart TD
S(["开始"]) --> Load["按ID加载用户"]
Load --> Found{"用户是否存在？"}
Found --> |否| NoData["返回无数据"]
Found --> |是| Parse["解析status/is_super_admin/password"]
Parse --> SA{"是否涉及超级管理员变更？"}
SA --> |是| CountSA["统计其他有效超级管理员数量"]
CountSA --> LastSA{"是否为最后一位？"}
LastSA --> |是| Block["阻止：至少保留一位超级管理员"]
LastSA --> |否| Next
SA --> |否| Next["继续"]
Next --> Passwd{"是否提供新密码？"}
Passwd --> |是| Hash["生成新密码哈希并保存"]
Passwd --> |否| Save["直接保存状态与角色"]
Hash --> Save
Save --> Log["记录日志"]
Log --> OK(["结束"])
Block --> OK
NoData --> OK

图表来源

章节来源

删除用户

  • 方法：DELETE
  • 路径：/api/users/:user_id
  • 限制：
    • 不允许删除当前登录用户
    • 不允许删除最后一个超级管理员
sequenceDiagram
participant FE as "前端"
participant API as "DELETE /api/users/ : user_id"
participant MODEL as "DashboardUser"
participant COUNT as "计数器"
FE->>API : "提交删除请求"
API->>MODEL : "按ID查找用户"
MODEL-->>API : "返回用户或空"
API->>COUNT : "统计其他有效超级管理员"
COUNT-->>API : "返回数量"
API-->>FE : "返回统一响应"

图表来源

章节来源

权限控制与角色管理

  • 认证中间件：
    • 解析Authorization头中的Bearer Token
    • 解码并注入用户上下文（id、username、is_super_admin）
    • 过期或无效令牌返回401
  • 超级管理员校验：
    • 仅is_super_admin为真时放行
    • 否则返回403
  • 角色与状态：
    • 字段is_super_admin与status均为TinyInt，1表示启用/是，0表示禁用/否
    • 默认status=1，is_super_admin=0
classDiagram
class AuthMiddleware {
+authMiddleware(req,res,next)
+requireSuperAdmin(req,res,next)
}
class DashboardUser {
+id : int
+username : string
+password_hash : string
+is_super_admin : int
+status : int
+last_login_at : date
+create_at : date
+update_at : date
}
AuthMiddleware --> DashboardUser : "读取用户状态"

图表来源

章节来源

密码重置与账户激活

  • 密码重置（当前用户）：
    • 路由：PUT /api/auth/password
    • 参数：old_password、new_password（长度>=6）
    • 流程：校验旧密码，通过后更新为新密码哈希
  • 账户激活：
    • 用户状态由status字段控制，1为启用，0为禁用
    • 通过更新用户状态实现“激活/禁用”
sequenceDiagram
participant FE as "前端"
participant AUTH as "PUT /api/auth/password"
participant MODEL as "DashboardUser"
participant PWD as "verifyPassword/hashPassword"
FE->>AUTH : "提交旧密码与新密码"
AUTH->>MODEL : "按ID加载用户"
MODEL-->>AUTH : "返回用户或空"
AUTH->>PWD : "校验旧密码"
PWD-->>AUTH : "返回校验结果"
AUTH->>PWD : "生成新密码哈希"
AUTH->>MODEL : "保存新密码哈希"
AUTH-->>FE : "返回成功消息"

图表来源

章节来源

批量操作与导入导出

  • 批量操作建议：
    • 使用循环调用单条更新接口（如批量启用/禁用、批量改密）
    • 在前端对用户ID集合进行分批处理，避免超时
  • 导入导出建议：
    • 导出：后端提供CSV/Excel导出接口，读取用户列表并序列化
    • 导入：前端上传文件，后端解析后逐条调用创建接口；注意幂等性与重复用户名处理
    • 安全性：导入过程建议增加事务与回滚策略，失败时撤销已创建记录

[本节为通用实现建议，不直接对应具体源文件]

前后端交互示例

  • 前端API封装：
    • GET /users/：分页查询
    • POST /users/：创建用户
    • PUT /users/:id：更新用户
    • DELETE /users/:id：删除用户
  • 前端页面：
    • 支持搜索、分页、启用/禁用切换、改密、删除
    • 通过Element Plus对话框与表格展示用户列表
sequenceDiagram
participant UI as "用户管理页面(index.vue)"
participant API as "API封装(user.js)"
participant USERS as "用户路由(users.js)"
UI->>API : "调用获取/创建/更新/删除"
API->>USERS : "转发HTTP请求"
USERS-->>API : "返回统一响应"
API-->>UI : "渲染结果"

图表来源

章节来源

依赖关系分析

  • 路由依赖：
    • users路由依赖auth中间件与DashboardUser模型
    • auth路由依赖jwt工具与password工具
  • 工具依赖：
    • password工具依赖crypto与pbkdf2
    • response工具提供统一响应结构
  • 引导依赖：
    • userBootstrap在应用启动时同步数据库并创建超级管理员
graph LR
USERS["users.js"] --> AUTHMW["auth.js"]
USERS --> MODEL["DashboardUser.js"]
USERS --> PWD["password.js"]
USERS --> RESP["response.js"]
AUTH["auth.js"] --> JWT["jwt.js"]
AUTH --> PWD
BOOT["userBootstrap.js"] --> MODEL

图表来源

章节来源

性能考虑

  • 分页与查询：
    • 限制limit上限为1000，避免大结果集导致内存压力
    • username模糊查询使用索引优化（建议在数据库层面建立索引）
  • 密码哈希：
    • PBKDF2迭代次数较高，保证安全性的同时需关注CPU开销
  • 日志与错误：
    • 统一使用logger记录错误堆栈，便于定位性能瓶颈

[本节提供通用指导，不直接分析具体文件]

故障排除指南

  • 401 未登录或缺少凭证：
    • 检查Authorization头格式是否为Bearer Token
    • 核对JWT_SECRET配置与签名算法
  • 403 需要超级管理员权限：
    • 确认当前用户is_super_admin为真
  • 404 账号不存在：
    • 确认用户ID正确且未被删除
  • 422 数据校验失败：
    • 用户名长度、密码长度、状态值范围不符合要求
  • 423 不能删除/禁用最后一个超级管理员：
    • 至少保留一位有效超级管理员

章节来源

结论

用户管理API以清晰的分层架构实现了完整的用户生命周期管理，结合严格的权限控制与安全的密码策略，满足后台管理系统对账号安全与合规性的需求。通过统一的响应封装与前端交互组件，提升了开发效率与用户体验。建议在生产环境中进一步完善批量导入导出、审计日志与速率限制等能力。

附录

  • 环境变量：
    • JWT_SECRET：用于JWT签名的密钥
    • DASHBOARD_ADMIN_USERNAME / DASHBOARD_ADMIN_PASSWORD：引导创建超级管理员的默认凭据
  • 健康检查：
    • GET /health 返回服务健康状态

章节来源

Reference in New Issue View Git Blame Copy Permalink