fa6f1e5c58
- 数据库：auth_roles 表新增 level 字段（1=超管, 10=管理员, 100=普通用户） - 后端：新增 GetAllRoles/GetUserMaxLevel/SetUserRoles/FindByCodeList DAO 方法 - 后端：SetRolesRequest 替换 AssignRoleRequest，AdminUserInfo.Roles 改为 []RoleInfo - 后端：所有管理操作（禁用/启用/角色分配/创建用户）强制层级权限校验 - 后端：PUT /users/:id/roles（批量设置角色）+ GET /roles（角色列表） - 前端：角色管理改为 Checkbox Group 多选，高等级角色禁用 - 前端：禁用/启用按钮受角色层级约束，列表页操作按钮权限管控 - 前端：创建用户对话框角色选项根据操作者等级动态过滤 - 文档：API 文档、设计方案、集成规范、进度文档同步更新 Made-with: Cursor
253 lines
6.5 KiB
Markdown
253 lines
6.5 KiB
Markdown
# 管理端 — 用户管理 API
|
||
|
||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](../README.md)
|
||
> 以下所有接口均需要 **JWT 认证 + admin/super_admin 角色**
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/admin/users | admin | 获取用户列表 |
|
||
| GET | /api/v1/admin/users/:id | admin | 获取用户详情 |
|
||
| PUT | /api/v1/admin/users/:id/status | admin | 更新用户状态（受角色等级约束） |
|
||
| PUT | /api/v1/admin/users/:id/roles | admin / super_admin | 批量设置用户角色（受角色等级约束） |
|
||
| POST | /api/v1/admin/users | admin | 管理员创建用户 |
|
||
| GET | /api/v1/admin/roles | admin | 获取所有角色列表（含 level） |
|
||
| GET | /api/v1/admin/users/:id/meetings | admin | 获取用户会议记录（Phase 3 实现） |
|
||
|
||
---
|
||
|
||
## 1. 获取用户列表
|
||
|
||
`GET /api/v1/admin/users`
|
||
|
||
**权限：** admin
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| page | int | 是 | - | 页码（从 1 开始） |
|
||
| page_size | int | 是 | - | 每页数量（1-100） |
|
||
| keyword | string | 否 | 无 | 搜索关键词（模糊匹配用户名或邮箱） |
|
||
| status | int | 否 | 无 | 按状态筛选：1=正常，2=禁用，3=注销 |
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 100,
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"username": "zhangsan",
|
||
"email": "zhangsan@example.com",
|
||
"nickname": "张三",
|
||
"avatar": "",
|
||
"gender": 1,
|
||
"phone": "13800138000",
|
||
"status": 1,
|
||
"status_text": "正常",
|
||
"roles": [
|
||
{ "code": "user", "name": "普通用户", "level": 100 }
|
||
],
|
||
"max_level": 100,
|
||
"last_login_at": "2026-02-27 10:00:00",
|
||
"last_login_ip": "192.168.1.100",
|
||
"created_at": "2026-02-20 08:00:00",
|
||
"updated_at": "2026-02-27 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 获取用户详情
|
||
|
||
`GET /api/v1/admin/users/:id`
|
||
|
||
**权限：** admin
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "zhangsan",
|
||
"email": "zhangsan@example.com",
|
||
"nickname": "张三",
|
||
"avatar": "",
|
||
"gender": 1,
|
||
"phone": "13800138000",
|
||
"status": 1,
|
||
"status_text": "正常",
|
||
"roles": [
|
||
{ "code": "user", "name": "普通用户", "level": 100 }
|
||
],
|
||
"max_level": 100,
|
||
"last_login_at": "2026-02-27 10:00:00",
|
||
"last_login_ip": "192.168.1.100",
|
||
"created_at": "2026-02-20 08:00:00",
|
||
"updated_at": "2026-02-27 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 更新用户状态
|
||
|
||
`PUT /api/v1/admin/users/:id/status`
|
||
|
||
**权限：** admin
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| status | int | 是 | 目标状态：1=正常（启用），2=禁用 |
|
||
|
||
**说明：**
|
||
- 禁用用户后，该用户的所有活跃 Token 将被清除
|
||
- 不能禁用自己的账号（返回 400）
|
||
- 操作者权限等级必须高于目标用户（level 数值更小），否则返回 403
|
||
- 禁用后用户尝试登录将返回 403
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"trace_id": "...",
|
||
"time": "2026-03-02 11:12:44"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 批量设置用户角色
|
||
|
||
`PUT /api/v1/admin/users/:id/roles`
|
||
|
||
**权限：** admin / super_admin
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| role_codes | string[] | 是 | 角色代码列表，如 `["user", "admin"]` |
|
||
|
||
**权限管控规则：**
|
||
- 操作者权限等级（level）必须严格高于目标用户（数值更小），否则返回 403
|
||
- 不能分配等级高于或等于操作者自身的角色，否则返回 403
|
||
- 角色列表为全量覆盖（先清除再设置）
|
||
- 注：`super_admin` 角色（level=1）不可通过 API 分配（任何人的 level 都 >= 1），超管只能通过数据库直接创建
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
- 403：`权限不足，无法操作更高等级的用户` 或 `不能分配高于自身等级的角色`
|
||
|
||
---
|
||
|
||
## 5. 获取所有角色列表
|
||
|
||
`GET /api/v1/admin/roles`
|
||
|
||
**权限：** admin
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": [
|
||
{ "code": "super_admin", "name": "超级管理员", "level": 1 },
|
||
{ "code": "admin", "name": "管理员", "level": 10 },
|
||
{ "code": "user", "name": "普通用户", "level": 100 }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 管理员创建用户
|
||
|
||
`POST /api/v1/admin/users`
|
||
|
||
**权限：** admin
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| username | string | 是 | 用户名，3-50 字符 |
|
||
| email | string | 是 | 邮箱地址 |
|
||
| password | string | 是 | 初始密码，6-50 字符 |
|
||
| nickname | string | 否 | 昵称（默认使用用户名） |
|
||
| role_code | string | 否 | 指定角色，默认为 user |
|
||
|
||
**权限管控规则：**
|
||
- 不能为新用户分配等级高于或等于操作者自身的角色，否则返回 403
|
||
- 例：admin（level=10）只能分配 level > 10 的角色（如 user），不能分配 admin 或 super_admin
|
||
|
||
**错误响应：**
|
||
- 400：`用户名或邮箱已被注册` / `无效的角色代码`
|
||
- 403：`不能分配高于自身等级的角色`
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 6,
|
||
"username": "created_by_admin",
|
||
"email": "admin_created@example.com",
|
||
"nickname": "管理员创建",
|
||
"avatar": "",
|
||
"gender": 0,
|
||
"status": 1,
|
||
"status_text": "正常",
|
||
"roles": [
|
||
{ "code": "user", "name": "普通用户", "level": 100 }
|
||
],
|
||
"max_level": 100,
|
||
"created_at": "2026-03-02 11:12:33",
|
||
"updated_at": "2026-03-02 11:12:33"
|
||
},
|
||
"trace_id": "...",
|
||
"time": "2026-03-02 11:12:33"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 获取用户会议记录
|
||
|
||
`GET /api/v1/admin/users/:id/meetings`
|
||
|
||
**权限：** admin
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| status | string | 无 | ongoing=进行中，upcoming=即将开始，ended=已结束 |
|
||
| page | int | 1 | 页码 |
|
||
| page_size | int | 20 | 每页数量 |
|