二级学院管理 API 接口文档

模块概述

模块名称：collegemsg / 二级学院管理
基础路径：/system/dept
版本：v1.0
负责人：Cursor AI
更新时间：2025-12-26

模块功能

二级学院管理模块主要用于管理学校的二级学院组织信息，通过sys_dept表存储学院基本信息，包括学院名称、负责人、联系方式等。支持二级学院的增删改查操作，为学校组织架构管理提供基础数据支撑。

权限说明

权限前缀：collegemsg:
权限列表：
- collegemsg:college:list - 查询权限
- collegemsg:college:add - 新增权限
- collegemsg:college:edit - 编辑权限
- collegemsg:college:remove - 删除权限

📊 接口概览

接口分类

基础 CRUD 接口

接口名称	HTTP 方法	路径	权限要求	功能描述
查询二级学院列表	GET	`/system/dept/list`	`collegemsg:college:list`	分页查询二级学院列表
查询二级学院详情	GET	`/system/dept/{deptId}`	`collegemsg:college:list`	根据 ID 查询二级学院详情
新增二级学院	POST	`/system/dept`	`collegemsg:college:add`	创建新的二级学院
修改二级学院	PUT	`/system/dept`	`collegemsg:college:edit`	更新二级学院信息
删除二级学院	DELETE	`/system/dept/{deptId}`	`collegemsg:college:remove`	删除二级学院

通用响应格式

成功响应

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        // 响应数据
    }
}

分页响应

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        // 数据列表
    ],
    "total": 100
}

错误响应

{
    "code": 400001,
    "msg": "参数错误",
    "data": null
}

🔍 接口详细说明

1. 查询二级学院列表

接口信息

接口地址: GET /system/dept/list

接口描述: 分页查询二级学院列表，支持多条件筛选，固定查询parent_id=101的二级学院

权限要求: collegemsg:college:list

请求参数

参数名	类型	必填	说明	示例值
pageNum	Integer	N	页码，默认 1	1
pageSize	Integer	N	每页大小，默认 10	10
deptName	String	N	学院名称	"计算机学院"
deptCategory	String	N	部门类别编码	"COLLEGE"
status	String	N	状态：0 正常，1 停用	"0"
parentId	Integer	Y	父节点ID，固定为101	101

请求示例

curl -X GET "http://localhost:8080/system/dept/list?pageNum=1&pageSize=10&deptName=计算机&parentId=101" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        {
            "deptId": 102,
            "parentId": 101,
            "deptName": "计算机学院",
            "deptCategory": "COLLEGE",
            "orderNum": 1,
            "status": "0",
            "delFlag": "0",
            "createBy": 1,
            "createTime": "2025-12-26 10:00:00",
            "updateBy": 1,
            "updateTime": "2025-12-26 10:00:00"
        }
    ],
    "total": 1
}

错误码

错误码	说明	解决方案
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限
400001	参数错误	检查请求参数格式

2. 查询二级学院详情

接口信息

接口地址: GET /system/dept/{deptId}

接口描述: 根据部门ID查询二级学院的详细信息

权限要求: collegemsg:college:list

路径参数

参数名	类型	必填	说明	示例值
deptId	Long	Y	部门ID	102

请求示例

curl -X GET "http://localhost:8080/system/dept/102" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "deptId": 102,
        "parentId": 101,
        "deptName": "计算机学院",
        "deptCategory": "COLLEGE",
        "orderNum": 1,
        "leader": "1",
        "phone": "13800138000",
        "email": "computer@school.edu.cn",
        "status": "0",
        "delFlag": "0",
        "remark": "计算机科学与技术专业",
        "createBy": 1,
        "createTime": "2025-12-26 10:00:00",
        "updateBy": 1,
        "updateTime": "2025-12-26 10:00:00"
    }
}

错误码

错误码	说明	解决方案
404001	数据不存在	检查 ID 是否正确
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

3. 新增二级学院

接口信息

接口地址: POST /system/dept

接口描述: 创建新的二级学院记录，自动设置parentId为101

权限要求: collegemsg:college:add

请求参数

参数名	类型	必填	说明	示例值
parentId	Integer	Y	父节点ID，固定为101	101
deptName	String	Y	学院名称	"计算机学院"
deptCategory	String	Y	部门类别编码	"COLLEGE"
orderNum	Integer	Y	显示顺序	1
status	String	Y	状态：0 正常，1 停用	"0"
remark	String	N	备注信息	"计算机科学与技术专业"

请求体

{
    "parentId": 101,
    "deptName": "计算机学院",
    "deptCategory": "COLLEGE",
    "orderNum": 1,
    "status": "0"
}

请求示例

curl -X POST "http://localhost:8080/system/dept" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": 101,
    "deptName": "计算机学院",
    "deptCategory": "COLLEGE",
    "orderNum": 1,
    "leader": "1",
    "phone": "13800138000",
    "email": "computer@school.edu.cn",
    "status": "0",
    "remark": "计算机科学与技术专业"
  }'

响应示例

{
    "code": 200,
    "msg": "新增成功",
    "data": {
        "deptId": 102
    }
}

错误码

错误码	说明	解决方案
400001	参数错误	检查必填参数是否缺失
400002	数据已存在	检查学院名称是否重复
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

参数验证规则

deptName: 长度 2-50 字符，不能为空
deptCategory: 长度 1-30 字符，不能为空
orderNum: 必须为正整数
status: 只能为 "0" 或 "1"

4. 修改二级学院

接口信息

接口地址: PUT /system/dept

接口描述: 更新二级学院信息

权限要求: collegemsg:college:edit

请求参数

参数名	类型	必填	说明	示例值
deptId	Integer	Y	部门ID	102
parentId	Integer	Y	父节点ID，固定为101	101
deptName	String	Y	学院名称	"计算机学院"
deptCategory	String	Y	部门类别编码	"COLLEGE"
orderNum	Integer	Y	显示顺序	1
status	String	Y	状态：0 正常，1 停用	"0"
remark	String	N	备注信息	"计算机科学与技术专业"

请求体

{
    "deptId": 102,
    "parentId": 101,
    "deptName": "计算机与人工智能学院",
    "deptCategory": "COLLEGE",
    "orderNum": 1,
    "leader": "1",
    "phone": "13800138000",
    "email": "csai@school.edu.cn",
    "status": "0",
    "remark": "计算机科学与人工智能专业"
}

请求示例

curl -X PUT "http://localhost:8080/system/dept" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "deptId": 102,
    "parentId": 101,
    "deptName": "计算机与人工智能学院",
    "deptCategory": "COLLEGE",
    "orderNum": 1,
    "leader": "1",
    "phone": "13800138000",
    "email": "csai@school.edu.cn",
    "status": "0",
    "remark": "计算机科学与人工智能专业"
  }'

响应示例

{
    "code": 200,
    "msg": "修改成功",
    "data": null
}

错误码

错误码	说明	解决方案
404001	数据不存在	检查 ID 是否正确
400001	参数错误	检查参数格式是否正确
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

5. 删除二级学院

接口信息

接口地址: DELETE /system/dept/{deptId}

接口描述: 删除二级学院，支持逻辑删除

权限要求: collegemsg:college:remove

路径参数

参数名	类型	必填	说明	示例值
deptId	Long	Y	部门ID	102

请求示例

curl -X DELETE "http://localhost:8080/system/dept/102" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "删除成功",
    "data": null
}

错误码

错误码	说明	解决方案
400001	参数错误	检查 ID 格式是否正确
400003	数据被引用	请先删除关联数据
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

📋 数据字典

二级学院状态枚举

值	名称	说明
0	正常	学院正常运行
1	停用	学院已停用

部门类别枚举

值	名称	说明
COLLEGE	学院	二级学院

🔧 SDK 使用示例

JavaScript SDK

// 查询二级学院列表
const queryParams = {
  pageNum: 1,
  pageSize: 10,
  deptName: "计算机",
  parentId: 101
};
const listResult = await listCollege(queryParams);

// 新增二级学院
const collegeData = {
  parentId: 101,
  deptName: "计算机学院",
  deptCategory: "COLLEGE",
  orderNum: 1,
  status: "0"
};
const addResult = await addCollege(collegeData);

// 修改二级学院
collegeData.deptId = 102;
collegeData.deptName = "计算机与人工智能学院";
const updateResult = await updateCollege(collegeData);

// 删除二级学院
const deleteResult = await delCollege(102);

🧪 测试用例

接口测试

// Jest 测试示例
describe('二级学院管理 API Tests', () => {
  test('查询二级学院列表接口', async () => {
    const response = await request(app)
      .get('/system/dept/list?parentId=101')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.code).toBe(200);
    expect(response.body.rows).toBeDefined();
    expect(response.body.total).toBeGreaterThanOrEqual(0);
  });

  test('新增二级学院接口', async () => {
    const collegeData = {
      parentId: 101,
      deptName: "测试学院",
      deptCategory: "COLLEGE",
      orderNum: 1,
      status: "0"
    };

    const response = await request(app)
      .post('/system/dept')
      .set('Authorization', `Bearer ${token}`)
      .send(collegeData)
      .expect(200);

    expect(response.body.code).toBe(200);
    expect(response.body.data.deptId).toBeDefined();
  });
});

🔄 版本历史

v1.0.0 - 2025-12-26

✅ 初始版本发布
✅ 完成基础 CRUD 接口
✅ 完成二级学院管理功能

📖 相关文档

数据库设计：数据库设计文档
业务需求：业务需求文档
技术架构：技术架构文档
开发规范：开发规范文档

📞 联系方式

开发团队：Cursor AI
负责人：Cursor AI
邮箱：无
文档维护：实时更新，如有问题请及时反馈

📌 重要提醒：

所有接口都需要先登录获取 token
请求头必须包含 Authorization: Bearer {token}
新增和修改操作会自动设置 parentId 为 101
学院名称具有唯一性约束
删除操作会进行关联数据检查
生产环境请使用 HTTPS 协议

二级学院管理API.md 14 KB Verlauf Originalformat

二级学院管理 API 接口文档

模块概述

模块功能

权限说明

📊 接口概览

接口分类

基础 CRUD 接口

通用响应格式

成功响应

分页响应

错误响应

🔍 接口详细说明

1. 查询二级学院列表

接口信息

请求参数

请求示例

响应示例

错误码

2. 查询二级学院详情

接口信息

路径参数

请求示例

响应示例

错误码

3. 新增二级学院

接口信息

请求参数

请求体

请求示例

响应示例

错误码

参数验证规则

4. 修改二级学院

接口信息

请求参数

请求体

请求示例

响应示例

错误码

5. 删除二级学院

接口信息

路径参数

请求示例

响应示例

错误码

📋 数据字典

二级学院状态枚举

部门类别枚举

🔧 SDK 使用示例

JavaScript SDK

🧪 测试用例

接口测试

🔄 版本历史

v1.0.0 - 2025-12-26

📖 相关文档

📞 联系方式

二级学院管理API.md 14 KB

Verlauf Originalformat