部门管理接口文档

一、部门管理接口

1. 获取部门树

接口地址： GET /sys/dept/tree

请求参数： 无

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "name": "默认部门",
            "parentId": 0,
            "memberCount": 15,
            "children": [
                {
                    "id": 2,
                    "name": "技术部",
                    "parentId": 1,
                    "memberCount": 8,
                    "children": []
                }
            ]
        }
    ]
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息，成功为 success
data	Array	部门树列表
data[].id	Long	部门 ID
data[].name	String	部门名称
data[].parentId	Long	父部门 ID，顶级部门通常为 0
data[].memberCount	Integer	成员数量，包含当前部门及所有子部门成员数
data[].children	Array	子部门列表

说明：

• 成员数量通过服务层递归计算，包含子部门成员。
• 部门树返回结构对应 SysDeptTreeVO。

---

2. 新增部门

接口地址： POST /sys/dept/save

请求参数：

{
    "id": null,
    "parentId": 1,
    "name": "技术部",
    "description": "负责技术研发"
}

请求字段说明：

字段	类型	必填	说明
id	Long	否	部门 ID，新增时通常不传
parentId	Long	是	上级部门 ID，顶级部门可传 0
name	String	是	部门名称，最大长度 20
description	String	否	部门描述，最大长度 100

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	成功时为 null

校验说明：

• 部门名称不能为空。
• 部门名称最大长度 20。
• 部门名称只能包含中文、英文和数字。
• 部门描述最大长度 100。
• 同一上级部门下部门名称不能重复。

错误示例：

{
    "code": 500,
    "msg": "部门名称不能为空。",
    "data": null
}

---

3. 修改部门

接口地址： POST /sys/dept/update

请求参数：

{
    "id": 2,
    "parentId": 1,
    "name": "技术研发部",
    "description": "负责平台研发与维护"
}

请求字段说明：

字段	类型	必填	说明
id	Long	是	部门 ID
parentId	Long	是	上级部门 ID
name	String	是	部门名称，最大长度 20
description	String	否	部门描述，最大长度 100

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	成功时为 null

校验说明：

• 部门 ID 不能为空。
• 部门名称不能为空。
• 部门名称最大长度 20。
• 部门名称只能包含中文、英文和数字。
• 部门描述最大长度 100。
• 同一上级部门下部门名称不能重复。
• 不能将部门设置为自己的子部门。

错误示例：

{
    "code": 500,
    "msg": "不能将部门设置为自己的子部门",
    "data": null
}

---

4. 删除部门

接口地址： GET /sys/dept/delete/{id}

路径参数：

• id: 部门 ID

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	成功时为 null

校验说明：

• 部门不存在时不允许删除。
• 该部门下存在子部门时不允许删除。
• 该部门下存在成员时不允许删除。

错误示例：

{
    "code": 500,
    "msg": "该部门下存在子部门，无法删除",
    "data": null
}

{
    "code": 500,
    "msg": "该部门下存在成员，无法删除",
    "data": null
}

---

5. 获取部门下拉选项列表

接口地址： GET /sys/dept/options

请求参数： 无

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "name": "默认部门"
        },
        {
            "id": 2,
            "name": "技术部"
        },
        {
            "id": 3,
            "name": "测试部"
        }
    ]
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息，成功为 success
data	Array	部门选项列表
data[].id	Long	部门 ID
data[].name	String	部门名称

说明：

• 该接口用于新增/编辑部门时选择上级部门。
• 前端需在列表最前面添加"无（顶级部门）"选项，ID 为 0。

---

二、部门成员管理接口

1. 分页查询部门成员

接口地址： POST /sys/dept/member/page

请求参数：

{
    "deptId": 1,
    "pageNum": 1,
    "pageSize": 20
}

请求字段说明：

字段	类型	必填	说明
deptId	Long	是	部门 ID
pageNum	Integer	否	页码，默认 1，最小 1
pageSize	Integer	否	每页条数，默认 20，最小 1，最大 200

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "records": [
            {
                "id": 1,
                "nickName": "张三",
                "username": "zhangsan",
                "roleNames": "平台管理员,平台运营",
                "status": 1,
                "createTime": "2026-04-20 10:00:00"
            }
        ],
        "total": 1,
        "size": 20,
        "current": 1,
        "pages": 1
    }
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	分页数据对象
data.records	Array	当前页成员列表
data.records[].id	Long	用户 ID
data.records[].nickName	String	用户姓名/昵称
data.records[].username	String	用户账号
data.records[].roleNames	String	角色名称，多个角色通常以字符串形式返回
data.records[].status	Integer	用户状态
data.records[].createTime	String	创建时间，格式 yyyy-MM-dd HH:mm:ss
data.total	Long	总记录数
data.size	Integer	每页条数
data.current	Integer	当前页码
data.pages	Integer	总页数

说明：

• 查询 DTO 继承 PageRequest，默认分页参数由代码控制：pageNum=1、pageSize=20、pageSize 最大 200。
• 返回对象对应 DeptMemberVO，实际包含 roleNames、createTime 字段。

---

2. 新增成员到部门

接口地址： POST /sys/dept/member/add

请求参数：

{
    "deptId": 1,
    "userIds": [1, 2, 3]
}

请求字段说明：

字段	类型	必填	说明
deptId	Long	是	部门 ID
userIds	List	是	用户 ID 列表

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	成功时为 null

说明：

• 已存在于该部门的成员会被跳过，不重复新增。

---

3. 移除部门成员

接口地址： POST /sys/dept/member/remove

请求参数：

{
    "deptId": 1,
    "userIds": [1, 2]
}

请求字段说明：

字段	类型	必填	说明
deptId	Long	是	部门 ID
userIds	List	是	用户 ID 列表

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	成功时为 null

---

4. 编辑成员所属部门

接口地址： POST /sys/dept/member/update

请求参数：

{
    "userId": 1,
    "deptIds": [1, 2, 3]
}

请求字段说明：

字段	类型	必填	说明
userId	Long	是	用户 ID
deptIds	List	是	部门 ID 列表

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码，成功为 200
msg	String	响应消息
data	Object	成功时为 null

说明：

• 该接口执行全量更新。
• 服务层会先移除用户已有部门关系，再批量写入新的部门关系。

---

三、错误码说明

错误码	说明
200	请求成功
500	服务器内部错误或业务校验失败
403	无访问权限

常见错误信息：

• 部门名称不能为空
• 部门名称长度不能超过%s位
• 部门名称只能包含中文、英文和数字
• 部门描述长度不能超过%s位
• 部门不存在
• 同一上级部门下部门名称已存在
• 该部门下存在子部门，无法删除
• 该部门下存在成员，无法删除
• 不能将部门设置为自己的子部门
• 部门ID不能为空
• 用户ID不能为空
• 用户ID列表不能为空
• 部门ID列表不能为空

---