427 lines
7.0 KiB
Markdown
427 lines
7.0 KiB
Markdown
# 用户模块接口文档
|
||
|
||
基础路径：`POST /mgt/user/*`，需 JWT 认证。
|
||
|
||
---
|
||
|
||
## 1. 新增用户
|
||
|
||
**路径**：`POST /mgt/user/create`
|
||
|
||
**请求体**（UserRequest）：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| account | string | 是 | 账户，3-50 位，创建时必填 |
|
||
| phone | string | 是 | 手机号，创建时必填 |
|
||
| password | string | 是 | 密码，6-50 位，创建时必填 |
|
||
| name | string | 否 | 名称，最长 100 |
|
||
| email | string | 否 | 邮箱 |
|
||
| avatar | string | 否 | 头像 URL，最长 500 |
|
||
| roles | string | 否 | 角色（预留） |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"account": "zhangsan",
|
||
"phone": "13800138000",
|
||
"password": "abc12345",
|
||
"name": "张三",
|
||
"email": "zhangsan@example.com"
|
||
}
|
||
```
|
||
|
||
**返回**（IdResp）：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | number | 用户 ID |
|
||
| identity | string | 用户唯一标识 |
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 删除用户
|
||
|
||
**路径**：`POST /mgt/user/del`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number | 是 | 用户 ID |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 用户详情
|
||
|
||
**路径**：`POST /mgt/user/detail`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number | 是 | 用户 ID |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
**返回**（UserResp）：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | number | 用户 ID |
|
||
| identity | string | 唯一标识 |
|
||
| account | string | 账户 |
|
||
| name | string | 姓名 |
|
||
| phone | string | 手机号 |
|
||
| email | string | 邮箱 |
|
||
| avatar | string | 头像 |
|
||
| status | number | 状态 |
|
||
| created_at | string | 创建时间 |
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
|
||
"account": "zhangsan",
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"email": "zhangsan@example.com",
|
||
"avatar": "https://example.com/avatar.png",
|
||
"status": 1,
|
||
"created_at": "2025-03-16 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 修改用户
|
||
|
||
**路径**：`POST /mgt/user/modify`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number | 是 | 用户 ID |
|
||
| name | string | 否 | 名称 |
|
||
| phone | string | 否 | 手机号 |
|
||
| email | string | 否 | 邮箱 |
|
||
| avatar | string | 否 | 头像 URL |
|
||
| password | string | 否 | 新密码，6-50 位 |
|
||
| status | number | 否 | 状态 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "张三丰",
|
||
"phone": "13900139000"
|
||
}
|
||
```
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 获取用户列表（分页）
|
||
|
||
**路径**：`POST /mgt/user/fetch`
|
||
|
||
**请求体**（继承 FetchBase）：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | number | 否 | 页码，默认 1 |
|
||
| size | number | 否 | 每页条数 |
|
||
| keyword | string | 否 | 关键字，模糊匹配姓名/账户/手机号 |
|
||
| status | number | 否 | 状态筛选 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"page": 1,
|
||
"size": 10,
|
||
"keyword": "张",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
**返回**（FetchResp，data 为 UserResp 数组）：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| total | number | 总条数 |
|
||
| page | number | 当前页 |
|
||
| size | number | 每页条数 |
|
||
| data | array | 用户列表 |
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"total": 2,
|
||
"page": 1,
|
||
"size": 10,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
|
||
"account": "zhangsan",
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"email": "zhangsan@example.com",
|
||
"avatar": "",
|
||
"status": 1,
|
||
"created_at": "2025-03-16 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 用户列表（下拉，不分页）
|
||
|
||
**路径**：`POST /mgt/user/list`
|
||
|
||
**说明**：按应用编码 workspace 查询该应用下用户，用于下拉选择。
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| workspace | string | 是 | 应用编码 |
|
||
| keyword | string | 否 | 关键字，模糊匹配姓名 |
|
||
| status | number | 否 | 状态 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"workspace": "my_app",
|
||
"keyword": "张"
|
||
}
|
||
```
|
||
|
||
**返回**（FetchResp，data 为 UserResp 数组，无分页字段）：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
|
||
"account": "zhangsan",
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"email": "zhangsan@example.com",
|
||
"avatar": "",
|
||
"status": 1,
|
||
"created_at": "2025-03-16 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 给用户设置角色
|
||
|
||
**路径**：`POST /mgt/user/set_role`
|
||
|
||
**请求体**（UserRoleRequest）：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| user_id | number | 是 | 用户 ID，大于 0 |
|
||
| role_id | number[] | 是 | 角色 ID 列表，至少 1 个，每个大于 0 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"user_id": 1,
|
||
"role_id": [1, 2]
|
||
}
|
||
```
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": ""
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 给用户移除角色
|
||
|
||
**路径**：`POST /mgt/user/del_role`
|
||
|
||
**请求体**：同 set_role，user_id + role_id 数组。
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"user_id": 1,
|
||
"role_id": [2]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 获取用户角色列表
|
||
|
||
**路径**：`POST /mgt/user/role`
|
||
|
||
**请求体**：FetchBase，传 id 表示用户 ID。
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
**返回**：data 为角色列表（含 id、identity、name 等）。
|
||
|
||
---
|
||
|
||
## 10. 给用户设置权限
|
||
|
||
**路径**：`POST /mgt/user/set_pmn`
|
||
|
||
**请求体**（AddPmnRequest）：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| workspace | string | 否 | 应用编码 |
|
||
| id | number | 是 | 用户 ID |
|
||
| list | number[] | 是 | 权限 ID 列表，至少 1 个 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"workspace": "my_app",
|
||
"id": 1,
|
||
"list": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 给用户编辑权限（按应用覆盖）
|
||
|
||
**路径**：`POST /mgt/user/modify_pmn`
|
||
|
||
**请求体**：同 set_pmn，按应用维度覆盖该用户在该应用下的权限。
|
||
|
||
---
|
||
|
||
## 12. 给用户移除权限
|
||
|
||
**路径**：`POST /mgt/user/del_pmn`
|
||
|
||
**请求体**：同 set_pmn，list 为要移除的权限 ID 列表。
|
||
|
||
---
|
||
|
||
## 13. 获取用户应用列表
|
||
|
||
**路径**：`POST /mgt/user/app`
|
||
|
||
**请求体**：FetchBase，id 为用户 ID。
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 获取用户权限列表（平面）
|
||
|
||
**路径**：`POST /mgt/user/pmn`
|
||
|
||
**请求体**：FetchBase，id 为用户 ID，可选 workspace 过滤应用。
|
||
|
||
---
|
||
|
||
## 15. 获取用户权限树（用户->应用->权限）
|
||
|
||
**路径**：`POST /mgt/user/pmn_tree`
|
||
|
||
**请求体**：同上。
|
||
|
||
**返回**：data 为按应用聚合的权限树结构。
|