276 lines
4.1 KiB
Markdown
276 lines
4.1 KiB
Markdown
# 角色模块接口文档
|
||
|
||
基础路径：`POST /mgt/role/*`，需 JWT 认证。
|
||
|
||
---
|
||
|
||
## 1. 新增角色
|
||
|
||
**路径**：`POST /mgt/role/create`
|
||
|
||
**请求体**（RoleReq）：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | 是 | 角色名称，1-100 位 |
|
||
| description | string | 否 | 角色描述，最长 1000 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"name": "管理员",
|
||
"description": "系统管理员，拥有全部权限"
|
||
}
|
||
```
|
||
|
||
**返回**（IdResp）：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 删除角色
|
||
|
||
**路径**：`POST /mgt/role/del`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number | 是 | 角色 ID |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 角色详情
|
||
|
||
**路径**：`POST /mgt/role/detail`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number | 是 | 角色 ID |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
**返回**：data 为角色对象（id、identity、name、description、status、created_at 等）。
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
|
||
"name": "管理员",
|
||
"description": "系统管理员，拥有全部权限",
|
||
"status": 1,
|
||
"created_at": "2025-03-16 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 修改角色
|
||
|
||
**路径**：`POST /mgt/role/modify`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number | 是 | 角色 ID |
|
||
| name | string | 否 | 角色名称 |
|
||
| description | string | 否 | 角色描述 |
|
||
| status | number | 否 | 状态 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "超级管理员",
|
||
"description": "超级管理员角色"
|
||
}
|
||
```
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 获取角色列表（分页）
|
||
|
||
**路径**：`POST /mgt/role/fetch`
|
||
|
||
**请求体**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | number | 否 | 页码 |
|
||
| size | number | 否 | 每页条数 |
|
||
| keyword | string | 否 | 关键字，模糊匹配名称 |
|
||
| status | number | 否 | 状态 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"page": 1,
|
||
"size": 10,
|
||
"keyword": "管理",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
**返回**（FetchResp）：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"total": 1,
|
||
"page": 1,
|
||
"size": 10,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
|
||
"name": "管理员",
|
||
"description": "系统管理员，拥有全部权限",
|
||
"status": 1,
|
||
"created_at": "2025-03-16 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 获取角色用户列表
|
||
|
||
**路径**：`POST /mgt/role/user`
|
||
|
||
**请求体**：FetchBase，id 为角色 ID。
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 获取角色应用列表
|
||
|
||
**路径**：`POST /mgt/role/app`
|
||
|
||
**请求体**：同上。
|
||
|
||
---
|
||
|
||
## 8. 给角色设置权限
|
||
|
||
**路径**：`POST /mgt/role/set_pmn`
|
||
|
||
**请求体**（AddPmnRequest）：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| workspace | string | 否 | 应用编码 |
|
||
| id | number | 是 | 角色 ID |
|
||
| list | number[] | 是 | 权限 ID 列表，至少 1 个 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"workspace": "my_app",
|
||
"id": 1,
|
||
"list": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 给角色编辑权限（按应用覆盖）
|
||
|
||
**路径**：`POST /mgt/role/modify_pmn`
|
||
|
||
**请求体**：同 set_pmn。
|
||
|
||
---
|
||
|
||
## 10. 给角色移除权限
|
||
|
||
**路径**：`POST /mgt/role/del_pmn`
|
||
|
||
**请求体**：同 set_pmn，list 为要移除的权限 ID 列表。
|
||
|
||
---
|
||
|
||
## 11. 获取角色权限列表（平面）
|
||
|
||
**路径**：`POST /mgt/role/pmn`
|
||
|
||
**请求体**：FetchBase，id 为角色 ID，可选 workspace 过滤应用。
|
||
|
||
---
|
||
|
||
## 12. 获取角色权限树（角色->应用->权限）
|
||
|
||
**路径**：`POST /mgt/role/pmn_tree`
|
||
|
||
**请求体**：同上。
|
||
|
||
**返回**：data 为按应用聚合的权限树。
|