# 部门模块接口文档

基础路径：`POST /mgt/dpt/*`，需 JWT 认证。  
部门按应用维度隔离：创建/列表/树等接口需传 `workspace` 表示所属应用。

---

## 1. 新增部门

**路径**：`POST /mgt/dpt/create`

**请求体**（DptReq）：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workspace | string | 是 | 应用编码，部门归属应用 |
| name | string | 是 | 部门名称，1-100 位，同应用下唯一 |
| parent_id | number | 否 | 父部门 ID，0 或不传表示顶级 |
| leader_id | number | 否 | 部门负责人用户 ID |

**请求示例**：

```json
{
  "workspace": "my_app",
  "name": "技术部",
  "parent_id": 0,
  "leader_id": 1
}
```

**返回**（IdResp）：

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

---

## 2. 删除部门

**路径**：`POST /mgt/dpt/del`

**说明**：会级联删除该部门及所有子部门，并清理部门-用户、部门-角色、部门-权限关联。

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | 是 | 部门 ID |

**请求示例**：

```json
{
  "id": 1
}
```

**返回示例**：

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

---

## 3. 部门详情

**路径**：`POST /mgt/dpt/detail`

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | 是 | 部门 ID |

**请求示例**：

```json
{
  "id": 1
}
```

**返回**：data 含部门基础信息及负责人（leader）简要信息。

| 参数 | 类型 | 说明 |
|------|------|------|
| id | number | 部门 ID |
| identity | string | 唯一标识 |
| name | string | 部门名称 |
| app_id | number | 应用 ID |
| parent_id | number | 父部门 ID |
| leader_id | number | 负责人用户 ID |
| leader | object | 负责人信息（id、identity、name） |

**返回示例**：

```json
{
  "code": 0,
  "data": {
    "id": 1,
    "identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "name": "技术部",
    "app_id": 1,
    "parent_id": 0,
    "leader_id": 1,
    "leader": {
      "id": 1,
      "identity": "01HXXX",
      "name": "张三"
    }
  }
}
```

---

## 4. 修改部门

**路径**：`POST /mgt/dpt/modify`

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | 是 | 部门 ID |
| name | string | 否 | 部门名称，同应用下唯一 |
| parent_id | number | 否 | 父部门 ID（不能为自己或当前部门的子孙） |
| leader_id | number | 否 | 负责人用户 ID |
| status | number | 否 | 状态 |

**请求示例**：

```json
{
  "id": 1,
  "name": "研发技术部",
  "parent_id": 0,
  "leader_id": 2
}
```

**返回示例**：

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

---

## 5. 获取部门列表（分页）

**路径**：`POST /mgt/dpt/fetch`

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workspace | string | 是 | 应用编码 |
| page | number | 否 | 页码 |
| size | number | 否 | 每页条数 |
| keyword | string | 否 | 关键字，模糊匹配部门名称 |
| status | number | 否 | 状态 |
| id | number | 否 | 指定部门 ID |
| parent_id | number | 否 | 按父部门 ID 筛选 |

**请求示例**：

```json
{
  "workspace": "my_app",
  "page": 1,
  "size": 10,
  "keyword": "技术",
  "status": 1
}
```

**返回**（FetchResp，data 为部门对象数组，含 id、identity、name、app_id、parent_id）：

```json
{
  "code": 0,
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "data": [
      {
        "id": 1,
        "identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "name": "技术部",
        "app_id": 1,
        "parent_id": 0
      }
    ]
  }
}
```

---

## 6. 部门列表（下拉/树）

**路径**：`POST /mgt/dpt/list`

**说明**：必传 workspace；`tree=true` 时返回树形结构，否则返回扁平列表。

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workspace | string | 是 | 应用编码 |
| keyword | string | 否 | 关键字，模糊匹配部门名称 |
| status | number | 否 | 状态 |
| tree | bool | 否 | true 时返回树形（含 children） |

**请求示例（扁平）**：

```json
{
  "workspace": "my_app",
  "keyword": "技术"
}
```

**请求示例（树形）**：

```json
{
  "workspace": "my_app",
  "tree": true
}
```

**返回示例（树形）**：

```json
{
  "code": 0,
  "data": {
    "data": [
      {
        "id": 1,
        "identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "name": "技术部",
        "app_id": 1,
        "parent_id": 0,
        "children": [
          {
            "id": 2,
            "identity": "01ARZ3NDEKTSV4RRFFQ69G5FBW",
            "name": "前端组",
            "app_id": 1,
            "parent_id": 1,
            "children": []
          }
        ]
      }
    ]
  }
}
```

---

## 7. 获取部门树

**路径**：`POST /mgt/dpt/fetch_tree`

**说明**：必传 workspace，返回该应用下完整部门树。

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workspace | string | 是 | 应用编码 |

**请求示例**：

```json
{
  "workspace": "my_app"
}
```

**返回**：data 为树形部门数组（结构同 list tree=true）。

---

## 8. 给部门设置权限

**路径**：`POST /mgt/dpt/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/dpt/modify_pmn`

**请求体**：同 set_pmn，按应用维度覆盖该部门在该应用下的权限。

---

## 10. 移除部门权限

**路径**：`POST /mgt/dpt/del_pmn`

**请求体**：同 set_pmn；**list 必填且至少一个元素**，为要移除的权限 ID 列表。

**请求示例**：

```json
{
  "workspace": "my_app",
  "id": 1,
  "list": [2, 3]
}
```

---

## 11. 获取部门权限列表（平面）

**路径**：`POST /mgt/dpt/pmn`

**说明**：可选 id 指定部门、workspace 过滤应用；**传 workspace 时仅返回该应用下部门权限**。

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | 否 | 部门 ID，不传则查所有部门 |
| workspace | string | 否 | 应用编码，过滤应用维度 |

**请求示例**：

```json
{
  "id": 1,
  "workspace": "my_app"
}
```

**返回**：data 为部门列表，每项含 id、identity、name 及 permissions 数组。

---

## 12. 获取部门权限树

**路径**：`POST /mgt/dpt/pmn_tree`

**说明**：部门下权限按父子建树；**传 workspace 时仅返回该应用下部门权限**。

**请求体**：同 pmn 接口（id、workspace 可选）。

**返回**：data 为部门列表，每项的 permissions 为树形权限结构。

---

## 13. 用户移入部门

**路径**：`POST /mgt/dpt/set_user`

**请求体**（DptUserRequest）：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dpt_id | number | 是 | 部门 ID，大于 0 |
| user_ids | number[] | 是 | 用户 ID 列表，至少 1 个，每个大于 0 |

**请求示例**：

```json
{
  "dpt_id": 1,
  "user_ids": [1, 2, 3]
}
```

**返回示例**：

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

---

## 14. 用户移出部门

**路径**：`POST /mgt/dpt/del_user`

**请求体**：同 set_user，user_ids 为要移出的用户 ID 列表。

**请求示例**：

```json
{
  "dpt_id": 1,
  "user_ids": [2]
}
```

---

## 15. 获取部门下用户列表

**路径**：`POST /mgt/dpt/user`

**说明**：**部门 ID 必传**，避免误用为“查全部部门用户”。

**请求体**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | 是 | 部门 ID |

**请求示例**：

```json
{
  "id": 1
}
```

**返回**：data 为部门列表（通常一条），每项含 id、identity、name 及 users 数组（用户 id、identity、name）。