844 lines
13 KiB
Markdown
844 lines
13 KiB
Markdown
# RBAC / 用户 / 菜单管理接口文档
|
||
|
||
本文档基于当前已落地代码整理，适合直接给前端联调使用。
|
||
|
||
## 1. 通用说明
|
||
|
||
### 1.1 响应结构
|
||
|
||
成功：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 20000,
|
||
"message": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"code": 40009,
|
||
"message": "具体错误信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 1.2 错误码使用习惯
|
||
|
||
| code | 说明 |
|
||
| ----- | -------------- |
|
||
| 20000 | 成功 |
|
||
| 40009 | 创建类失败 / 参数校验失败 |
|
||
| 40011 | 详情查询失败 |
|
||
| 40012 | 更新 / 删除 / 分配失败 |
|
||
|
||
### 1.3 当前实现注意事项
|
||
|
||
- 用户密码字段当前直接写入 `password_hash`，还未做真正加密
|
||
- 分配类接口均为覆盖式保存
|
||
- 当前密码字段是占位实现，后续建议替换为真实 hash
|
||
|
||
***
|
||
|
||
## 2. 角色管理
|
||
|
||
### 2.1 角色列表
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/role/list`
|
||
|
||
请求参数：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | -- | --------- |
|
||
| keyword | string | 否 | 角色名称模糊搜索 |
|
||
| status | int | 否 | 1启用 0禁用 |
|
||
| pageNo | int | 否 | 页码，默认1 |
|
||
| pageSize | int | 否 | 每页条数，默认20 |
|
||
|
||
返回 `data`：
|
||
|
||
```json
|
||
{
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"code": "admin",
|
||
"name": "超级管理员",
|
||
"description": "系统内置超级管理员",
|
||
"status": 1,
|
||
"is_system": 1,
|
||
"created_by": 1,
|
||
"created_time": "2025-01-01 10:00:00",
|
||
"updated_time": "2025-01-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### 2.2 角色详情
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/role/detail`
|
||
|
||
请求参数：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------ | --- | -- | ---- |
|
||
| roleId | int | 是 | 角色ID |
|
||
|
||
返回：单个角色对象。
|
||
|
||
### 2.3 创建角色
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/role/create`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"code": "test_manager",
|
||
"name": "测试经理",
|
||
"description": "测试经理角色",
|
||
"status": 1,
|
||
"isSystem": 0,
|
||
"createdBy": 1
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"id": 2
|
||
}
|
||
```
|
||
|
||
### 2.4 更新角色
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/role/update`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"roleId": 2,
|
||
"name": "高级测试经理",
|
||
"description": "升级后的测试经理角色"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"id": 2
|
||
}
|
||
```
|
||
|
||
### 2.5 删除角色
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/role/delete`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"roleId": 2
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"id": 2
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 3. 权限管理
|
||
|
||
### 3.1 权限列表
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/permission/list`
|
||
|
||
请求参数：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | -- | -------- |
|
||
| keyword | string | 否 | 权限名称模糊搜索 |
|
||
| module | string | 否 | 模块名 |
|
||
| status | int | 否 | 状态 |
|
||
| pageNo | int | 否 | 页码 |
|
||
| pageSize | int | 否 | 每页条数 |
|
||
|
||
返回 `data`：
|
||
|
||
```json
|
||
{
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"code": "user:create",
|
||
"name": "创建用户",
|
||
"module": "user",
|
||
"action": "create",
|
||
"description": "创建用户权限",
|
||
"status": 1,
|
||
"created_time": "2025-01-01 10:00:00",
|
||
"updated_time": "2025-01-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### 3.2 权限详情
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/permission/detail`
|
||
- 参数：`permissionId`
|
||
|
||
### 3.3 创建权限
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/permission/create`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"code": "user:create",
|
||
"name": "创建用户",
|
||
"module": "user",
|
||
"action": "create",
|
||
"description": "创建用户权限",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 3.4 更新权限
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/permission/update`
|
||
|
||
### 3.5 删除权限
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/permission/delete`
|
||
|
||
***
|
||
|
||
## 4. 菜单管理
|
||
|
||
### 4.1 菜单树
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/menu/tree`
|
||
|
||
请求参数：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------ | --- | -- | ---- |
|
||
| status | int | 否 | 状态过滤 |
|
||
|
||
返回 `data`：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"parent_id": 0,
|
||
"name": "系统管理",
|
||
"code": "system",
|
||
"type": 1,
|
||
"path": "/system",
|
||
"component": "Layout",
|
||
"icon": "setting",
|
||
"permission_code": null,
|
||
"sort": 1,
|
||
"visible": 1,
|
||
"status": 1,
|
||
"created_time": "2025-01-01 10:00:00",
|
||
"updated_time": "2025-01-01 10:00:00",
|
||
"children": [
|
||
{
|
||
"id": 2,
|
||
"parent_id": 1,
|
||
"name": "用户管理",
|
||
"code": "user_manage",
|
||
"type": 2,
|
||
"path": "/system/user",
|
||
"component": "system/user/index",
|
||
"icon": "user",
|
||
"permission_code": "user:list",
|
||
"sort": 1,
|
||
"visible": 1,
|
||
"status": 1,
|
||
"children": []
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
### 4.2 菜单详情
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/menu/detail`
|
||
- 参数：`menuId`
|
||
|
||
### 4.3 创建菜单
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/menu/create`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"parentId": 1,
|
||
"name": "角色管理",
|
||
"code": "role_manage",
|
||
"type": 2,
|
||
"path": "/system/role",
|
||
"component": "system/role/index",
|
||
"icon": "peoples",
|
||
"permissionCode": "role:list",
|
||
"sort": 2,
|
||
"visible": 1,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 4.4 更新菜单
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/menu/update`
|
||
|
||
### 4.5 删除菜单
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/menu/delete`
|
||
|
||
***
|
||
|
||
## 5. 角色权限分配
|
||
|
||
### 5.1 查询角色权限
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/role/permission/list`
|
||
- 参数：`roleId`
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"permissionIds": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
### 5.2 分配角色权限
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/role/permission/assign`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"roleId": 2,
|
||
"permissionIds": [1, 2, 3, 4]
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"id": 2
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 6. 角色菜单分配
|
||
|
||
### 6.1 查询角色菜单
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/role/menu/list`
|
||
- 参数：`roleId`
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"menuIds": [1, 2, 3, 4]
|
||
}
|
||
```
|
||
|
||
### 6.2 分配角色菜单
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/role/menu/assign`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"roleId": 2,
|
||
"menuIds": [1, 2, 10, 11]
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"id": 2
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 7. 用户管理
|
||
|
||
### 7.1 用户列表
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/user/list`
|
||
|
||
请求参数：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | -- | ------- |
|
||
| keyword | string | 否 | 用户名模糊搜索 |
|
||
| status | int | 否 | 状态 |
|
||
| pageNo | int | 否 | 页码 |
|
||
| pageSize | int | 否 | 每页条数 |
|
||
|
||
返回 `data`：
|
||
|
||
```json
|
||
{
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"username": "admin",
|
||
"real_name": "管理员",
|
||
"mobile": "13800000000",
|
||
"email": "admin@test.com",
|
||
"avatar": "",
|
||
"status": 1,
|
||
"last_login_time": "2025-01-01 10:00:00",
|
||
"created_by": 1,
|
||
"created_time": "2025-01-01 10:00:00",
|
||
"updated_time": "2025-01-01 10:00:00",
|
||
"role_ids": [1, 2],
|
||
"role_names": ["管理员", "测试经理"]
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### 7.2 用户详情
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/user/detail`
|
||
- 参数：`userId`
|
||
|
||
返回会额外包含：
|
||
|
||
```json
|
||
{
|
||
"role_ids": [1, 2]
|
||
}
|
||
```
|
||
|
||
### 7.3 创建用户
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/user/create`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"username": "zhangsan",
|
||
"password": "123456",
|
||
"realName": "张三",
|
||
"mobile": "13800001111",
|
||
"email": "zhangsan@test.com",
|
||
"avatar": "",
|
||
"status": 1,
|
||
"createdBy": 1
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"id": 3
|
||
}
|
||
```
|
||
|
||
### 7.4 更新用户
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/user/update`
|
||
|
||
### 7.5 删除用户
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/user/delete`
|
||
|
||
***
|
||
|
||
## 8. 用户角色分配
|
||
|
||
### 8.1 查询用户角色
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/user/role/list`
|
||
- 参数：`userId`
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"roleIds": [1, 2]
|
||
}
|
||
```
|
||
|
||
### 8.2 分配用户角色
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/user/role/assign`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"userId": 10,
|
||
"roleIds": [2, 3]
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"id": 10
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 9. 认证接口
|
||
|
||
### 9.1 注册
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/auth/register`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"username": "zhangsan",
|
||
"password": "123456",
|
||
"realName": "张三",
|
||
"mobile": "13800001111",
|
||
"email": "zhangsan@test.com",
|
||
"avatar": "",
|
||
"createdBy": 1
|
||
}
|
||
```
|
||
|
||
请求参数说明：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --------- | ------ | -- | --------------------------- |
|
||
| username | string | 是 | 登录用户名 |
|
||
| password | string | 是 | 登录密码，当前直接写入 `password_hash` |
|
||
| realName | string | 否 | 真实姓名 |
|
||
| mobile | string | 否 | 手机号 |
|
||
| email | string | 否 | 邮箱 |
|
||
| avatar | string | 否 | 头像 |
|
||
| createdBy | int | 否 | 创建人 |
|
||
|
||
成功返回：
|
||
|
||
```json
|
||
{
|
||
"id": 11
|
||
}
|
||
```
|
||
|
||
失败场景：
|
||
|
||
- `username、password 为必传参数`
|
||
- `用户名已存在！`
|
||
|
||
### 9.2 登录
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/auth/login`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"username": "zhangsan",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
请求参数说明：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | -- | ----- |
|
||
| username | string | 是 | 登录用户名 |
|
||
| password | string | 是 | 登录密码 |
|
||
|
||
成功返回 `data`：
|
||
|
||
```json
|
||
{
|
||
"id": 11,
|
||
"username": "zhangsan",
|
||
"real_name": "张三",
|
||
"mobile": "13800001111",
|
||
"email": "zhangsan@test.com",
|
||
"avatar": "",
|
||
"status": 1,
|
||
"last_login_time": null,
|
||
"created_by": 1,
|
||
"created_time": "2025-01-01 10:00:00",
|
||
"updated_time": "2025-01-01 10:00:00",
|
||
"role_ids": [2, 3]
|
||
}
|
||
```
|
||
|
||
失败场景：
|
||
|
||
- `username、password 为必传参数`
|
||
- `用户名或密码错误！`
|
||
- `用户已禁用！`
|
||
|
||
登录成功额外返回：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --------------------------- | ------ | ----------------------- |
|
||
| token | string | 登录令牌，存入 Redis |
|
||
| token\_type | string | 固定为 `Bearer` |
|
||
| expires\_in | int | token 过期时间，单位秒，当前为 7200 |
|
||
| refresh\_threshold\_seconds | int | 自动续期阈值，单位秒，当前为 1800 |
|
||
| refresh\_mechanism | string | 刷新机制说明 |
|
||
|
||
当前 token 机制：
|
||
|
||
- token 存储位置：Redis
|
||
- Redis key 前缀：`effekt:token:`
|
||
- token 过期时间：`7200` 秒（2小时）
|
||
- 刷新机制：访问任意需要登录的接口时，如果 token 剩余有效期小于 `1800` 秒，则自动续期到完整 2 小时
|
||
- 请求头支持：
|
||
- `accessToken`
|
||
- `accesstoken`
|
||
- `Authorization: Bearer <token>`
|
||
|
||
> 当前登录接口已返回 token、过期时间和刷新机制说明。
|
||
|
||
***
|
||
|
||
## 10. 一组联调示例
|
||
|
||
### 9.1 创建角色
|
||
|
||
```http
|
||
POST /role/create
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": "tester",
|
||
"name": "测试人员",
|
||
"description": "普通测试角色",
|
||
"status": 1,
|
||
"isSystem": 0
|
||
}
|
||
```
|
||
|
||
### 9.2 创建权限
|
||
|
||
```json
|
||
{
|
||
"code": "case:list",
|
||
"name": "查看用例列表",
|
||
"module": "case",
|
||
"action": "list",
|
||
"description": "查看测试用例列表",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 9.3 创建菜单
|
||
|
||
```json
|
||
{
|
||
"parentId": 1,
|
||
"name": "权限管理",
|
||
"code": "permission_manage",
|
||
"type": 2,
|
||
"path": "/system/permission",
|
||
"component": "system/permission/index",
|
||
"icon": "lock",
|
||
"permissionCode": "permission:list",
|
||
"sort": 3,
|
||
"visible": 1,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 9.4 给角色分配权限
|
||
|
||
```json
|
||
{
|
||
"roleId": 5,
|
||
"permissionIds": [1, 2, 3, 4]
|
||
}
|
||
```
|
||
|
||
### 9.5 给角色分配菜单
|
||
|
||
```json
|
||
{
|
||
"roleId": 5,
|
||
"menuIds": [1, 2, 8, 9]
|
||
}
|
||
```
|
||
|
||
### 9.6 创建用户
|
||
|
||
```json
|
||
{
|
||
"username": "lisi",
|
||
"password": "123456",
|
||
"realName": "李四",
|
||
"mobile": "13800002222",
|
||
"email": "lisi@test.com",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 10.7 给用户分配角色
|
||
|
||
```json
|
||
{
|
||
"userId": 10,
|
||
"roleIds": [5]
|
||
}
|
||
```
|
||
|
||
### 10.8 注册
|
||
|
||
```json
|
||
{
|
||
"username": "new_user",
|
||
"password": "123456",
|
||
"realName": "新用户",
|
||
"mobile": "13800009999",
|
||
"email": "new_user@test.com"
|
||
}
|
||
```
|
||
|
||
### 10.9 登录
|
||
|
||
```json
|
||
{
|
||
"username": "new_user",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
### 10.10 鉴权说明
|
||
|
||
请求受保护接口时，请在请求头中携带以下任意一种：
|
||
|
||
```text
|
||
accessToken: <token>
|
||
```
|
||
|
||
或
|
||
|
||
```text
|
||
accesstoken: <token>
|
||
```
|
||
|
||
或
|
||
|
||
```text
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
当前机制：
|
||
|
||
- token 存 Redis
|
||
- 默认有效期：2 小时
|
||
- 剩余有效期小于 30 分钟时，访问受保护接口会自动续期
|
||
- 注册、登录接口不需要 token
|
||
- 其他接口已逐步接入登录鉴权与权限限制
|
||
|
||
***
|
||
|
||
## 11. 当前初始化 SQL 已包含的业务菜单
|
||
|
||
已补入以下可直接录入的菜单数据：
|
||
|
||
### 系统管理
|
||
|
||
- `system` 系统管理
|
||
- `role_manage` 角色管理
|
||
- `user_manage` 用户管理
|
||
- `permission_manage` 权限管理
|
||
- `menu_manage` 菜单管理
|
||
|
||
### 测试平台
|
||
|
||
- `test_platform` 测试平台
|
||
- `product_manage` 产品管理
|
||
- `project_manage` 项目管理
|
||
- `case_manage` 用例管理
|
||
- `plan_manage` 测试计划
|
||
- `report_manage` 测试报告
|
||
|
||
### 造数工具
|
||
|
||
- `data_tools` 造数工具
|
||
- `data_builder_manage` 数据库造数
|
||
- `data_factory_manage` 造数工厂
|
||
|
||
如果后续你要，我可以继续补：
|
||
|
||
1. Swagger/OpenAPI 版本
|
||
2. Apifox / Postman 导入版
|
||
3. 初始化权限菜单角色的更完整种子数据
|
||
|