469 lines
8.2 KiB
Markdown
469 lines
8.2 KiB
Markdown
# 部门模块接口文档
|
||
|
||
基础路径：`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）。
|