full/module/base/mgt/doc/role.md

# 角色模块接口文档

基础路径：`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 为按应用聚合的权限树。