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

用户模块接口文档

基础路径：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	否	角色（预留）

请求示例：

{
  "account": "zhangsan",
  "phone": "13800138000",
  "password": "abc12345",
  "name": "张三",
  "email": "zhangsan@example.com"
}

返回（IdResp）：

参数	类型	说明
id	number	用户 ID
identity	string	用户唯一标识

返回示例：

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

---

2. 删除用户

路径：POST /mgt/user/del

请求体：

参数	类型	必填	说明
id	number	是	用户 ID

请求示例：

{
  "id": 1
}

返回示例：

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

---

3. 用户详情

路径：POST /mgt/user/detail

请求体：

参数	类型	必填	说明
id	number	是	用户 ID

请求示例：

{
  "id": 1
}

返回（UserResp）：

参数	类型	说明
id	number	用户 ID
identity	string	唯一标识
account	string	账户
name	string	姓名
phone	string	手机号
email	string	邮箱
avatar	string	头像
status	number	状态
created_at	string	创建时间

返回示例：

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

请求示例：

{
  "id": 1,
  "name": "张三丰",
  "phone": "13900139000"
}

返回示例：

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

---

5. 获取用户列表（分页）

路径：POST /mgt/user/fetch

请求体（继承 FetchBase）：

参数	类型	必填	说明
page	number	否	页码，默认 1
size	number	否	每页条数
keyword	string	否	关键字，模糊匹配姓名/账户/手机号
status	number	否	状态筛选

请求示例：

{
  "page": 1,
  "size": 10,
  "keyword": "张",
  "status": 1
}

返回（FetchResp，data 为 UserResp 数组）：

参数	类型	说明
total	number	总条数
page	number	当前页
size	number	每页条数
data	array	用户列表

返回示例：

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

请求示例：

{
  "workspace": "my_app",
  "keyword": "张"
}

返回（FetchResp，data 为 UserResp 数组，无分页字段）：

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

请求示例：

{
  "user_id": 1,
  "role_id": [1, 2]
}

返回示例：

{
  "code": 0,
  "data": ""
}

---

8. 给用户移除角色

路径：POST /mgt/user/del_role

请求体：同 set_role，user_id + role_id 数组。

请求示例：

{
  "user_id": 1,
  "role_id": [2]
}

---

9. 获取用户角色列表

路径：POST /mgt/user/role

请求体：FetchBase，传 id 表示用户 ID。

请求示例：

{
  "id": 1
}

返回：data 为角色列表（含 id、identity、name 等）。

---

10. 给用户设置权限

路径：POST /mgt/user/set_pmn

请求体（AddPmnRequest）：

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

请求示例：

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

请求示例：

{
  "id": 1
}

---

14. 获取用户权限列表（平面）

路径：POST /mgt/user/pmn

请求体：FetchBase，id 为用户 ID，可选 workspace 过滤应用。

---

15. 获取用户权限树（用户->应用->权限）

路径：POST /mgt/user/pmn_tree

请求体：同上。

返回：data 为按应用聚合的权限树结构。