部门管理接口文档

本接口用于对系统中的**部门（Department）**资源进行全生命周期管理，遵循 RESTful 设计规范，以 HTTP 方法语义化操作，统一使用 JSON 格式进行数据交互。

资源路径：/system/dept-api
实体类：DeptDTO（增删改查共用）

---

公共请求头

⚠️ 注意：本接口需携带有效的 access_token 进行身份验证，未授权访问将被拒绝。

Header 参数（http header）

参数名	类型	必填	说明
Authorization	String	是	请求令牌，Bearer <access_token>

---

接口列表

操作	方法	路径	说明
创建部门	POST	/system/dept-api	新增一个部门
查询部门	GET	/system/dept-api/{id}	根据 dept_id 获取部门详情
更新部门	PUT	/system/dept-api	全量更新部门信息
删除部门	DELETE	/system/dept-api/{id}	根据 dept_id 删除部门
批量删除	DELETE	/system/dept-api/{ids}	批量删除多个部门（逗号分隔）

实体类定义（DeptDTO）

所有接口的请求体（Request Body）或返回数据（Response Data）均基于以下结构：

JSON 示例

点击展开 JSON 数据

{
  "deptId": 101,
  "parentId": 100,
  "ancestors": "0,100",
  "deptName": "技术研发部",
  "orderNum": 2,
  "leader": "张三",
  "phone": "13800138000",
  "email": "zhangsan@example.com",
  "status": "0",
  "delFlag": "0",
  "tenantId": "000000"
}

字段说明

参数名	类型	必填	默认值	说明
deptId	Long	否	—	部门 ID（创建时不传，由服务端生成）
parentId	Long	是	0	父部门 ID；0 表示顶级部门
ancestors	String	否	""	祖级列表，格式如 "0,100,101"（从根到当前节点的 ID 路径）
deptName	String	是	""	部门名称
orderNum	Integer	否	0	显示顺序（数字越小越靠前）
leader	String	否	null	负责人姓名
phone	String	否	null	联系电话（建议 11 位手机号）
email	String	否	null	邮箱地址
status	String	否	"0"	部门状态： "0"：正常 "1"：停用
delFlag	String	否	"0"	删除标志： "0"：存在 "2"：已删除（逻辑删除）
tenantId	String	是	"000000"	所属租户编号

🔒 重要规则：

• ancestors 由系统自动生成，前端无需传入；
• 修改 parentId 时，系统自动更新 ancestors；
• 禁止形成循环引用（如 A → B → A）。

接口详情

创建部门（POST）

请求

POST /system/dept-api
Content-Type: application/json
Authorization: Bearer <token>

点击展开 JSON 数据

{
  "parentId": 100,
  "deptName": "前端开发组",
  "orderNum": 3,
  "leader": "李四",
  "phone": "13900139000",
  "email": "lisi@example.com",
  "status": "0",
  "tenantId": "000000"
}

✅ 注意：

• 不传 deptId 和 ancestors；
• parentId 必须是当前租户下已存在的有效部门 ID。

响应

点击展开 JSON 数据

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

查询部门（GET）

请求

GET /system/dept-api/101
Authorization: Bearer <token>

路径参数

参数	位置	必填	说明
id	path	是	部门 ID（dept_id）

响应

点击展开 JSON 数据

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "deptId": 101,
    "parentId": 100,
    "ancestors": "0,100",
    "deptName": "技术研发部",
    "orderNum": 2,
    "leader": "张三",
    "phone": "13800138000",
    "email": "zhangsan@example.com",
    "status": "0",
    "delFlag": "0",
    "tenantId": "000000",
    "createBy": "admin",
    "createTime": "2025-06-13 14:44:00",
    "updateBy": "",
    "updateTime": null
  }
}

更新部门（PUT）

请求

PUT /system/dept-api
Content-Type: application/json
Authorization: Bearer <token>

点击展开 JSON 数据

{
  "deptId": 101,
  "parentId": 100,
  "deptName": "后端研发部",
  "orderNum": 2,
  "leader": "王五",
  "phone": "13700137000",
  "email": "wangwu@example.com",
  "status": "0",
  "tenantId": "000000"
}

🔁 注意：

• 必须包含 deptId；
• 此为全量更新，未传字段可能被重置；
• 若 parentId 变更，系统将自动更新 ancestors。

响应

点击展开 JSON 数据

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

删除部门（DELETE）

请求

DELETE /system/dept-api/101
Authorization: Bearer <token>

路径参数

参数	位置	必填	说明
id	path	是	部门 ID

⚠️ 限制：若该部门下存在子部门或关联用户，则禁止删除。

响应

点击展开 JSON 数据

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

批量删除部门（DELETE）

请求

DELETE /system/dept-api/101,102,103
Authorization: Bearer <token>

支持逗号分隔多个 deptId

路径参数

参数	位置	必填	说明
ids	path	是	部门 ID 列表（如 101,102）

⚠️ 同样受“存在子部门或用户”限制。

响应

点击展开 JSON 数据

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

安全与注意事项

• 租户隔离：所有操作自动限定在当前用户所属租户（tenantId）；
• 逻辑删除：删除操作仅标记 del_flag = '2'，不物理删除；
• 数据一致性：修改父部门时，系统自动维护 ancestors 字段；
• 防循环依赖：后端校验禁止部门形成环形结构；
• 权限控制：仅“租户管理员”等高权限角色可管理组织架构。