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

角色模块接口文档

基础路径：POST /mgt/role/*，需 JWT 认证。

---

1. 新增角色

路径：POST /mgt/role/create

请求体（RoleReq）：

参数	类型	必填	说明
name	string	是	角色名称，1-100 位
description	string	否	角色描述，最长 1000

请求示例：

{
  "name": "管理员",
  "description": "系统管理员，拥有全部权限"
}

返回（IdResp）：

{
  "code": 0,
  "data": {
    "id": 1,
    "identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }
}

---

2. 删除角色

路径：POST /mgt/role/del

请求体：

参数	类型	必填	说明
id	number	是	角色 ID

请求示例：

{
  "id": 1
}

返回示例：

{
  "code": 0,
  "data": {
    "id": 1,
    "identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }
}

---

3. 角色详情

路径：POST /mgt/role/detail

请求体：

参数	类型	必填	说明
id	number	是	角色 ID

请求示例：

{
  "id": 1
}

返回：data 为角色对象（id、identity、name、description、status、created_at 等）。

返回示例：

{
  "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	否	状态

请求示例：

{
  "id": 1,
  "name": "超级管理员",
  "description": "超级管理员角色"
}

返回示例：

{
  "code": 0,
  "data": {
    "id": 1,
    "identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }
}

---

5. 获取角色列表（分页）

路径：POST /mgt/role/fetch

请求体：

参数	类型	必填	说明
page	number	否	页码
size	number	否	每页条数
keyword	string	否	关键字，模糊匹配名称
status	number	否	状态

请求示例：

{
  "page": 1,
  "size": 10,
  "keyword": "管理",
  "status": 1
}

返回（FetchResp）：

{
  "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。

请求示例：

{
  "id": 1
}

---

7. 获取角色应用列表

路径：POST /mgt/role/app

请求体：同上。

---

8. 给角色设置权限

路径：POST /mgt/role/set_pmn

请求体（AddPmnRequest）：

参数	类型	必填	说明
workspace	string	否	应用编码
id	number	是	角色 ID
list	number[]	是	权限 ID 列表，至少 1 个

请求示例：

{
  "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 为按应用聚合的权限树。