# 二级学院管理 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` | 删除二级学院 | ### 通用响应格式 #### 成功响应 ```json { "code": 200, "msg": "操作成功", "data": { // 响应数据 } } ``` #### 分页响应 ```json { "code": 200, "msg": "查询成功", "rows": [ // 数据列表 ], "total": 100 } ``` #### 错误响应 ```json { "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 | #### 请求示例 ```bash 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" ``` #### 响应示例 ```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 | #### 请求示例 ```bash curl -X GET "http://localhost:8080/system/dept/102" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" ``` #### 响应示例 ```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 | 备注信息 | "计算机科学与技术专业" | #### 请求体 ```json { "parentId": 101, "deptName": "计算机学院", "deptCategory": "COLLEGE", "orderNum": 1, "status": "0" } ``` #### 请求示例 ```bash 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": "计算机科学与技术专业" }' ``` #### 响应示例 ```json { "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 | 备注信息 | "计算机科学与技术专业" | #### 请求体 ```json { "deptId": 102, "parentId": 101, "deptName": "计算机与人工智能学院", "deptCategory": "COLLEGE", "orderNum": 1, "leader": "1", "phone": "13800138000", "email": "csai@school.edu.cn", "status": "0", "remark": "计算机科学与人工智能专业" } ``` #### 请求示例 ```bash 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": "计算机科学与人工智能专业" }' ``` #### 响应示例 ```json { "code": 200, "msg": "修改成功", "data": null } ``` #### 错误码 | 错误码 | 说明 | 解决方案 | | ------ | ---------- | -------------------- | | 404001 | 数据不存在 | 检查 ID 是否正确 | | 400001 | 参数错误 | 检查参数格式是否正确 | | 401001 | 未登录 | 请先登录获取 token | | 403001 | 无权限 | 请联系管理员分配权限 | --- ### 5. 删除二级学院 #### 接口信息 **接口地址**: `DELETE /system/dept/{deptId}` **接口描述**: 删除二级学院，支持逻辑删除 **权限要求**: `collegemsg:college:remove` #### 路径参数 | 参数名 | 类型 | 必填 | 说明 | 示例值 | | ------ | ---- | ---- | -------- | ------ | | deptId | Long | Y | 部门ID | 102 | #### 请求示例 ```bash curl -X DELETE "http://localhost:8080/system/dept/102" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" ``` #### 响应示例 ```json { "code": 200, "msg": "删除成功", "data": null } ``` #### 错误码 | 错误码 | 说明 | 解决方案 | | ------ | ---------- | -------------------- | | 400001 | 参数错误 | 检查 ID 格式是否正确 | | 400003 | 数据被引用 | 请先删除关联数据 | | 401001 | 未登录 | 请先登录获取 token | | 403001 | 无权限 | 请联系管理员分配权限 | --- ## 📋 数据字典 ### 二级学院状态枚举 | 值 | 名称 | 说明 | | --- | ---- | -------- | | 0 | 正常 | 学院正常运行 | | 1 | 停用 | 学院已停用 | ### 部门类别枚举 | 值 | 名称 | 说明 | | ------ | ---- | -------- | | COLLEGE | 学院 | 二级学院 | --- ## 🔧 SDK 使用示例 ### JavaScript SDK ```javascript // 查询二级学院列表 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); ``` --- ## 🧪 测试用例 ### 接口测试 ```javascript // 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 接口 - ✅ 完成二级学院管理功能 --- ## 📖 相关文档 - **数据库设计**：[数据库设计文档](../设计文档/database/) - **业务需求**：[业务需求文档](../需求文档/) - **技术架构**：[技术架构文档](./技术架构/) - **开发规范**：[开发规范文档](./开发规范/) --- ## 📞 联系方式 **开发团队**：Cursor AI **负责人**：Cursor AI **邮箱**：无 **文档维护**：实时更新，如有问题请及时反馈 --- **📌 重要提醒**： 1. 所有接口都需要先登录获取 token 2. 请求头必须包含 `Authorization: Bearer {token}` 3. 新增和修改操作会自动设置 parentId 为 101 4. 学院名称具有唯一性约束 5. 删除操作会进行关联数据检查 6. 生产环境请使用 HTTPS 协议