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

460 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 用户管理API
<cite>
**本文档引用的文件**
- [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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为系统“用户管理API”的详细RESTful接口文档，覆盖用户CRUD操作（列表查询、详情获取、创建、更新、删除）、权限控制与角色管理、状态控制、密码重置、账户激活以及批量操作与导入导出的实现指南。文档同时提供前后端交互流程图与最佳实践建议，帮助开发者快速集成与维护。
## 项目结构
后端采用Express + Sequelize架构，前端基于Vue3 + Element Plus。用户管理API位于独立路由模块中，并通过认证中间件进行统一鉴权。
```mermaid
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
```
**图表来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
- [backend/src/routes/users.js:1-180](file://backend/src/routes/users.js#L1-L180)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/models/DashboardUser.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
- [backend/src/utils/password.js:1-37](file://backend/src/utils/password.js#L1-L37)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
- [frontend/src/api/user.js:1-40](file://frontend/src/api/user.js#L1-L40)
- [frontend/src/views/system/users/index.vue:1-428](file://frontend/src/views/system/users/index.vue#L1-L428)
**章节来源**
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
## 核心组件
- 用户路由模块：提供用户CRUD接口，内置分页、模糊查询、状态与角色变更校验。
- 认证中间件：统一处理Bearer Token解析与超级管理员权限校验。
- 密码工具：PBKDF2哈希与校验，确保密码安全存储。
- 响应封装：统一封装成功/错误/无数据返回格式。
- 用户模型：定义字段类型、默认值与注释，支撑权限与状态控制。
- 引导服务：首次部署自动创建超级管理员账号。
**章节来源**
- [backend/src/routes/users.js:1-180](file://backend/src/routes/users.js#L1-L180)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/utils/password.js:1-37](file://backend/src/utils/password.js#L1-L37)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [backend/src/models/DashboardUser.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
## 架构总览
用户管理API遵循“路由-中间件-模型-工具”分层设计，所有用户管理接口均需通过认证中间件并具备超级管理员权限。
```mermaid
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响应"
```
**图表来源**
- [backend/src/routes/users.js:12-13](file://backend/src/routes/users.js#L12-L13)
- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
- [backend/src/models/DashboardUser.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
- [backend/src/utils/password.js:10-34](file://backend/src/utils/password.js#L10-L34)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
## 详细组件分析
### 接口清单与规范
- 基础路径：/api/users
- 认证方式：Authorization: Bearer <token>
- 权限要求：仅超级管理员可访问
- 分页参数：skip（起始偏移），limit（最大1000，默认100）
- 查询参数：username（模糊匹配）
**章节来源**
- [backend/src/routes/users.js:35-61](file://backend/src/routes/users.js#L35-L61)
- [backend/src/middleware/auth.js:3-33](file://backend/src/middleware/auth.js#L3-L33)
#### 列表查询
- 方法：GET
- 路径：/api/users/
- 请求参数：
- skip：数字，可选
- limit：数字，范围[1,1000]，默认100
- username：字符串，模糊查询用户名
- 成功响应：包含items、total、skip、limit的分页对象
- 错误响应：空数据时返回“无数据”标识
```mermaid
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 : "返回统一响应"
```
**图表来源**
- [backend/src/routes/users.js:35-61](file://backend/src/routes/users.js#L35-L61)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
**章节来源**
- [backend/src/routes/users.js:35-61](file://backend/src/routes/users.js#L35-L61)
#### 创建用户
- 方法：POST
- 路径：/api/users/
- 请求体字段：
- username：字符串，必填，长度<=64
- password：字符串，必填，长度>=6
- is_super_admin：布尔，可选，默认false
- 成功响应：返回创建的用户字典
- 限制：
- 用户名唯一
- 至少保留一个超级管理员（删除/降级时校验）
```mermaid
flowchart TD
Start(["开始"]) --> Validate["校验用户名与密码长度"]
Validate --> Exists{"用户名已存在？"}
Exists --> |是| ErrExists["返回错误：用户名已存在"]
Exists --> |否| Hash["生成密码哈希"]
Hash --> Create["创建用户记录"]
Create --> Log["记录日志"]
Log --> Done(["结束"])
ErrExists --> Done
```
**图表来源**
- [backend/src/routes/users.js:63-98](file://backend/src/routes/users.js#L63-L98)
- [backend/src/utils/password.js:10-14](file://backend/src/utils/password.js#L10-L14)
**章节来源**
- [backend/src/routes/users.js:63-98](file://backend/src/routes/users.js#L63-L98)
#### 更新用户
- 方法：PUT
- 路径：/api/users/:user_id
- 请求体字段：
- status：0或1，可选
- is_super_admin：布尔，可选
- password：字符串，可选（若提供则长度>=6）
- 成功响应：返回更新后的用户字典
- 限制：
- 不能禁用或降级最后一个超级管理员
- 当前登录用户不可自我删除
```mermaid
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
```
**图表来源**
- [backend/src/routes/users.js:100-147](file://backend/src/routes/users.js#L100-L147)
- [backend/src/utils/password.js:10-14](file://backend/src/utils/password.js#L10-L14)
**章节来源**
- [backend/src/routes/users.js:100-147](file://backend/src/routes/users.js#L100-L147)
#### 删除用户
- 方法：DELETE
- 路径：/api/users/:user_id
- 限制：
- 不允许删除当前登录用户
- 不允许删除最后一个超级管理员
```mermaid
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 : "返回统一响应"
```
**图表来源**
- [backend/src/routes/users.js:149-177](file://backend/src/routes/users.js#L149-L177)
**章节来源**
- [backend/src/routes/users.js:149-177](file://backend/src/routes/users.js#L149-L177)
### 权限控制与角色管理
- 认证中间件：
- 解析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
```mermaid
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 : "读取用户状态"
```
**图表来源**
- [backend/src/middleware/auth.js:3-33](file://backend/src/middleware/auth.js#L3-L33)
- [backend/src/models/DashboardUser.js:4-54](file://backend/src/models/DashboardUser.js#L4-L54)
**章节来源**
- [backend/src/middleware/auth.js:3-33](file://backend/src/middleware/auth.js#L3-L33)
- [backend/src/models/DashboardUser.js:22-33](file://backend/src/models/DashboardUser.js#L22-L33)
### 密码重置与账户激活
- 密码重置（当前用户）：
- 路由：PUT /api/auth/password
- 参数：old_password、new_password（长度>=6）
- 流程：校验旧密码，通过后更新为新密码哈希
- 账户激活：
- 用户状态由status字段控制，1为启用，0为禁用
- 通过更新用户状态实现“激活/禁用”
```mermaid
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 : "返回成功消息"
```
**图表来源**
- [backend/src/routes/auth.js:79-109](file://backend/src/routes/auth.js#L79-L109)
- [backend/src/utils/password.js:16-34](file://backend/src/utils/password.js#L16-L34)
**章节来源**
- [backend/src/routes/auth.js:79-109](file://backend/src/routes/auth.js#L79-L109)
- [backend/src/utils/password.js:16-34](file://backend/src/utils/password.js#L16-L34)
### 批量操作与导入导出
- 批量操作建议：
- 使用循环调用单条更新接口（如批量启用/禁用、批量改密）
- 在前端对用户ID集合进行分批处理，避免超时
- 导入导出建议：
- 导出：后端提供CSV/Excel导出接口，读取用户列表并序列化
- 导入：前端上传文件，后端解析后逐条调用创建接口；注意幂等性与重复用户名处理
- 安全性：导入过程建议增加事务与回滚策略，失败时撤销已创建记录
[本节为通用实现建议，不直接对应具体源文件]
### 前后端交互示例
- 前端API封装：
- GET /users/：分页查询
- POST /users/：创建用户
- PUT /users/:id：更新用户
- DELETE /users/:id：删除用户
- 前端页面：
- 支持搜索、分页、启用/禁用切换、改密、删除
- 通过Element Plus对话框与表格展示用户列表
```mermaid
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 : "渲染结果"
```
**图表来源**
- [frontend/src/views/system/users/index.vue:173-392](file://frontend/src/views/system/users/index.vue#L173-L392)
- [frontend/src/api/user.js:1-40](file://frontend/src/api/user.js#L1-L40)
- [backend/src/routes/users.js:35-177](file://backend/src/routes/users.js#L35-L177)
**章节来源**
- [frontend/src/api/user.js:1-40](file://frontend/src/api/user.js#L1-L40)
- [frontend/src/views/system/users/index.vue:173-392](file://frontend/src/views/system/users/index.vue#L173-L392)
## 依赖关系分析
- 路由依赖：
- users路由依赖auth中间件与DashboardUser模型
- auth路由依赖jwt工具与password工具
- 工具依赖：
- password工具依赖crypto与pbkdf2
- response工具提供统一响应结构
- 引导依赖：
- userBootstrap在应用启动时同步数据库并创建超级管理员
```mermaid
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
```
**图表来源**
- [backend/src/routes/users.js:1-180](file://backend/src/routes/users.js#L1-L180)
- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [backend/src/models/DashboardUser.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
- [backend/src/utils/password.js:1-37](file://backend/src/utils/password.js#L1-L37)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
**章节来源**
- [backend/src/routes/users.js:1-180](file://backend/src/routes/users.js#L1-L180)
- [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
## 性能考虑
- 分页与查询：
- 限制limit上限为1000，避免大结果集导致内存压力
- username模糊查询使用索引优化（建议在数据库层面建立索引）
- 密码哈希：
- PBKDF2迭代次数较高，保证安全性的同时需关注CPU开销
- 日志与错误：
- 统一使用logger记录错误堆栈，便于定位性能瓶颈
[本节提供通用指导，不直接分析具体文件]
## 故障排除指南
- 401 未登录或缺少凭证：
- 检查Authorization头格式是否为Bearer Token
- 核对JWT_SECRET配置与签名算法
- 403 需要超级管理员权限：
- 确认当前用户is_super_admin为真
- 404 账号不存在：
- 确认用户ID正确且未被删除
- 422 数据校验失败：
- 用户名长度、密码长度、状态值范围不符合要求
- 423 不能删除/禁用最后一个超级管理员：
- 至少保留一位有效超级管理员
**章节来源**
- [backend/src/middleware/auth.js:5-25](file://backend/src/middleware/auth.js#L5-L25)
- [backend/src/routes/users.js:105-128](file://backend/src/routes/users.js#L105-L128)
- [backend/src/routes/users.js:154-168](file://backend/src/routes/users.js#L154-L168)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
## 结论
用户管理API以清晰的分层架构实现了完整的用户生命周期管理，结合严格的权限控制与安全的密码策略，满足后台管理系统对账号安全与合规性的需求。通过统一的响应封装与前端交互组件，提升了开发效率与用户体验。建议在生产环境中进一步完善批量导入导出、审计日志与速率限制等能力。
## 附录
- 环境变量：
- JWT_SECRET：用于JWT签名的密钥
- DASHBOARD_ADMIN_USERNAME / DASHBOARD_ADMIN_PASSWORD：引导创建超级管理员的默认凭据
- 健康检查：
- GET /health 返回服务健康状态
**章节来源**
- [backend/src/utils/jwt.js:3-5](file://backend/src/utils/jwt.js#L3-L5)
- [backend/src/services/userBootstrap.js:9-22](file://backend/src/services/userBootstrap.js#L9-L22)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
Reference in New Issue View Git Blame Copy Permalink