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 | 否 | 角色（预留） |

**请求示例**：

```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 为按应用聚合的权限树结构。