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

部门模块接口文档

基础路径：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

请求示例：

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

返回（IdResp）：

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

---

2. 删除部门

路径：POST /mgt/dpt/del

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

请求体：

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

请求示例：

{
  "id": 1
}

返回示例：

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

---

3. 部门详情

路径：POST /mgt/dpt/detail

请求体：

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

请求示例：

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

返回示例：

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

请求示例：

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

返回示例：

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

请求示例：

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

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

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

请求示例（扁平）：

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

请求示例（树形）：

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

返回示例（树形）：

{
  "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	是	应用编码

请求示例：

{
  "workspace": "my_app"
}

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

---

8. 给部门设置权限

路径：POST /mgt/dpt/set_pmn

请求体（AddPmnRequest）：

参数	类型	必填	说明
workspace	string	否	应用编码，需与部门所属应用一致
id	number	是	部门 ID
list	number[]	是	权限 ID 列表，至少 1 个

请求示例：

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

请求示例：

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

---

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

路径：POST /mgt/dpt/pmn

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

请求体：

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

请求示例：

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

请求示例：

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

返回示例：

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

---

14. 用户移出部门

路径：POST /mgt/dpt/del_user

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

请求示例：

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

---

15. 获取部门下用户列表

路径：POST /mgt/dpt/user

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

请求体：

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

请求示例：

{
  "id": 1
}

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