diff --git a/docs/开发文档/API/API文档总览.md b/docs/开发文档/API/API文档总览.md index 61d90832..09677c11 100644 --- a/docs/开发文档/API/API文档总览.md +++ b/docs/开发文档/API/API文档总览.md @@ -100,6 +100,8 @@ | 日期 | 版本 | 更新内容 | 更新人 | |------|------|---------|-------| +| 2025-12-26 | 1.6 | 新增专业信息管理API，支持树形菜单+列表的专业管理 | Cursor | +| 2025-12-26 | 1.5 | 新增二级学院管理API，支持二级学院的增删改查 | Cursor | | 2025-01-03 | 1.1 | 社团管理API更新：删除副社长信息卡片，role_type字段改为字符串类型 | 系统管理员 | | 2025-07-01 | 1.0 | 初始版本 | 系统管理员 | | 2025-07-15 | 1.1 | 添加心理健康测评API | 张工 | @@ -167,6 +169,8 @@ | [学生信息收集批次管理API](./学生信息收集批次管理API.md) | 学生信息收集批次班级权限管理 | ✅ 完成 | 2025-01-27 | | [学生信息批次收集API](./学生信息批次收集API.md) | 学生信息批次收集管理（新增） | ✅ 完成 | 2025-01-27 | | [班级信息管理API](./班级信息管理API.md) | 班级基础信息增删改查 | ✅ 完成 | 2025-01-27 | +| [二级学院管理API](./二级学院管理API.md) | 二级学院组织信息管理 | ✅ 完成 | 2025-12-26 | +| [专业信息管理API](./专业信息管理API.md) | 专业信息管理（树形菜单+列表） | ✅ 完成 | 2025-12-26 | | [班级干部信息管理API](./班级干部信息管理API.md) | 班级干部信息管理（含用户角色关联） | ✅ 完成 | 2025-01-27 | | [班干部管理API](./班干部管理API.md) | 班级干部职务管理 | ✅ 完成 | 2025-01-27 | | [班级教师关联管理API](./班级教师关联管理API.md) | 班主任辅导员关联关系 | ✅ 完成 | 2025-01-27 | diff --git a/docs/开发文档/API/专业信息管理API.md b/docs/开发文档/API/专业信息管理API.md new file mode 100644 index 00000000..23798ee8 --- /dev/null +++ b/docs/开发文档/API/专业信息管理API.md @@ -0,0 +1,592 @@ +# 专业信息管理 API 接口文档 + +### 模块概述 + +**模块名称**：majormsg / 专业信息管理 +**基础路径**：`/system/dept` +**版本**：v1.0 +**负责人**：Cursor AI +**更新时间**：2025-12-26 + +### 模块功能 + +专业信息管理模块主要用于管理学校的专业组织信息，通过sys_dept表存储专业基本信息，包括专业名称、所属学院、类别编码等。支持专业信息的增删改查操作，为学校专业架构管理提供基础数据支撑。 + +专业信息通过 `dept_category` 字段以 "zy-" 开头进行标识，属于二级学院的下级组织。 + +### 权限说明 + +- **权限前缀**：`majormsg:` +- **权限列表**： + - `majormsg:major:list` - 查询权限 + - `majormsg:major:add` - 新增权限 + - `majormsg:major:edit` - 编辑权限 + - `majormsg:major:remove` - 删除权限 + +--- + +## 📊 接口概览 + +### 接口分类 + +#### 基础 CRUD 接口 + +| 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 | +| -------------- | --------- | --------------------- | ---------------------- | ---------------------- | +| 查询专业列表 | GET | `/system/dept/list` | `majormsg:major:list` | 分页查询专业列表 | +| 查询专业详情 | GET | `/system/dept/{deptId}` | `majormsg:major:list` | 根据 ID 查询专业详情 | +| 新增专业 | POST | `/system/dept` | `majormsg:major:add` | 创建新的专业 | +| 修改专业 | PUT | `/system/dept` | `majormsg:major:edit` | 更新专业信息 | +| 删除专业 | DELETE | `/system/dept/{deptId}` | `majormsg:major:remove` | 删除专业 | + +#### 业务逻辑接口 + +| 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 | +| ---------------- | --------- | ------------------- | --------------------- | ---------------- | +| 获取学院树结构 | GET | `/system/dept/list` | `majormsg:major:list` | 获取二级学院树结构 | + +### 通用响应格式 + +#### 成功响应 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + // 响应数据 + } +} +``` + +#### 分页响应 + +```json +{ + "code": 200, + "msg": "查询成功", + "rows": [ + // 数据列表 + ], + "total": 100 +} +``` + +#### 错误响应 + +```json +{ + "code": 400001, + "msg": "参数错误", + "data": null +} +``` + +--- + +## 🔍 接口详细说明 + +### 1. 查询专业列表 + +#### 接口信息 + +**接口地址**: `GET /system/dept/list` + +**接口描述**: 分页查询专业列表，支持多条件筛选，固定查询dept_category以"zy-"开头的数据 + +**权限要求**: `majormsg:major:list` + +#### 请求参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +| --------------- | ------- | ---- | ------------------------ | ------------ | +| pageNum | Integer | N | 页码，默认 1 | 1 | +| pageSize | Integer | N | 每页大小，默认 10 | 10 | +| deptName | String | N | 专业名称 | "计算机科学" | +| deptCategory | String | N | 部门类别编码 | "zy-001" | +| deptCategoryLike| String | Y | 部门类别模糊匹配（zy-） | "zy-" | +| parentId | Integer | N | 所属学院ID | 102 | +| status | String | N | 状态：0 正常，1 停用 | "0" | + +#### 请求示例 + +```bash +curl -X GET "http://localhost:8080/system/dept/list?pageNum=1&pageSize=10&deptCategoryLike=zy-" \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" +``` + +#### 响应示例 + +```json +{ + "code": 200, + "msg": "查询成功", + "rows": [ + { + "deptId": 201, + "parentId": 102, + "parentName": "计算机学院", + "deptName": "计算机科学与技术", + "deptCategory": "zy-001", + "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查询专业的详细信息 + +**权限要求**: `majormsg:major:list` + +#### 路径参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +| ------ | ---- | ---- | ------ | ------ | +| deptId | Long | Y | 部门ID | 201 | + +#### 请求示例 + +```bash +curl -X GET "http://localhost:8080/system/dept/201" \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" +``` + +#### 响应示例 + +```json +{ + "code": 200, + "msg": "查询成功", + "data": { + "deptId": 201, + "parentId": 102, + "parentName": "计算机学院", + "deptName": "计算机科学与技术", + "deptCategory": "zy-001", + "orderNum": 1, + "status": "0", + "delFlag": "0", + "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` + +**接口描述**: 创建新的专业记录，dept_category必须以"zy-"开头 + +**权限要求**: `majormsg:major:add` + +#### 请求参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +| ----------- | ------- | ---- | ---------------------------- | ------------------- | +| parentId | Integer | Y | 所属学院ID | 102 | +| deptName | String | Y | 专业名称 | "计算机科学与技术" | +| deptCategory| String | Y | 部门类别编码（必须以zy-开头）| "zy-001" | +| orderNum | Integer | Y | 显示顺序 | 1 | +| status | String | Y | 状态：0 正常，1 停用 | "0" | + +#### 请求体 + +```json +{ + "parentId": 102, + "deptName": "计算机科学与技术", + "deptCategory": "zy-001", + "orderNum": 1, + "status": "0" +} +``` + +#### 请求示例 + +```bash +curl -X POST "http://localhost:8080/system/dept" \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" \ + -d '{ + "parentId": 102, + "deptName": "计算机科学与技术", + "deptCategory": "zy-001", + "orderNum": 1, + "status": "0" + }' +``` + +#### 响应示例 + +```json +{ + "code": 200, + "msg": "新增成功", + "data": { + "deptId": 201 + } +} +``` + +#### 错误码 + +| 错误码 | 说明 | 解决方案 | +| ------ | ---------- | -------------------- | +| 400001 | 参数错误 | 检查必填参数是否缺失 | +| 400002 | 数据已存在 | 检查专业名称是否重复 | +| 401001 | 未登录 | 请先登录获取 token | +| 403001 | 无权限 | 请联系管理员分配权限 | + +#### 参数验证规则 + +- `parentId`: 必须是有效的二级学院ID +- `deptName`: 长度 2-50 字符，不能为空 +- `deptCategory`: 必须以 "zy-" 开头，长度 4-30 字符，不能为空 +- `orderNum`: 必须为正整数 +- `status`: 只能为 "0" 或 "1" + +--- + +### 4. 修改专业 + +#### 接口信息 + +**接口地址**: `PUT /system/dept` + +**接口描述**: 更新专业信息 + +**权限要求**: `majormsg:major:edit` + +#### 请求参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +| ----------- | ------- | ---- | ---------------------------- | ------------------- | +| deptId | Integer | Y | 专业ID | 201 | +| parentId | Integer | Y | 所属学院ID | 102 | +| deptName | String | Y | 专业名称 | "计算机科学与技术" | +| deptCategory| String | Y | 部门类别编码（必须以zy-开头）| "zy-001" | +| orderNum | Integer | Y | 显示顺序 | 1 | +| status | String | Y | 状态：0 正常，1 停用 | "0" | + +#### 请求体 + +```json +{ + "deptId": 201, + "parentId": 102, + "deptName": "计算机科学与技术（本）", + "deptCategory": "zy-001", + "orderNum": 1, + "status": "0" +} +``` + +#### 请求示例 + +```bash +curl -X PUT "http://localhost:8080/system/dept" \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" \ + -d '{ + "deptId": 201, + "parentId": 102, + "deptName": "计算机科学与技术（本）", + "deptCategory": "zy-001", + "orderNum": 1, + "status": "0" + }' +``` + +#### 响应示例 + +```json +{ + "code": 200, + "msg": "修改成功", + "data": null +} +``` + +#### 错误码 + +| 错误码 | 说明 | 解决方案 | +| ------ | ---------- | -------------------- | +| 404001 | 数据不存在 | 检查 ID 是否正确 | +| 400001 | 参数错误 | 检查参数格式是否正确 | +| 401001 | 未登录 | 请先登录获取 token | +| 403001 | 无权限 | 请联系管理员分配权限 | + +--- + +### 5. 删除专业 + +#### 接口信息 + +**接口地址**: `DELETE /system/dept/{deptId}` + +**接口描述**: 删除专业，支持逻辑删除 + +**权限要求**: `majormsg:major:remove` + +#### 路径参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +| ------ | ---- | ---- | -------- | ------ | +| deptId | Long | Y | 专业ID | 201 | + +#### 请求示例 + +```bash +curl -X DELETE "http://localhost:8080/system/dept/201" \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" +``` + +#### 响应示例 + +```json +{ + "code": 200, + "msg": "删除成功", + "data": null +} +``` + +#### 错误码 + +| 错误码 | 说明 | 解决方案 | +| ------ | ---------- | -------------------- | +| 400001 | 参数错误 | 检查 ID 格式是否正确 | +| 400003 | 数据被引用 | 请先删除关联数据 | +| 401001 | 未登录 | 请先登录获取 token | +| 403001 | 无权限 | 请联系管理员分配权限 | + +--- + +### 6. 获取学院树结构 + +#### 接口信息 + +**接口地址**: `GET /system/dept/list` + +**接口描述**: 获取二级学院的树形结构，用于左侧导航菜单 + +**权限要求**: `majormsg:major:list` + +#### 请求参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +| -------- | ------- | ---- | ---------------- | ------ | +| parentId | Integer | Y | 父节点ID（固定为101） | 101 | + +#### 请求示例 + +```bash +curl -X GET "http://localhost:8080/system/dept/list?parentId=101" \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" +``` + +#### 响应示例 + +```json +{ + "code": 200, + "msg": "查询成功", + "data": [ + { + "deptId": 102, + "parentId": 101, + "deptName": "计算机学院", + "deptCategory": "xy-19", + "orderNum": 1, + "status": "0" + }, + { + "deptId": 103, + "parentId": 101, + "deptName": "人文学院", + "deptCategory": "xy-19", + "orderNum": 2, + "status": "0" + } + ] +} +``` + +--- + +## 📋 数据字典 + +### 专业状态枚举 + +| 值 | 名称 | 说明 | +| --- | ---- | -------- | +| 0 | 正常 | 专业正常运行 | +| 1 | 停用 | 专业已停用 | + +### 专业类别编码规范 + +| 前缀 | 说明 | 示例 | +| ---- | ---- | ---- | +| zy- | 专业标识前缀 | zy-001（计算机科学与技术）
zy-002（软件工程） | + +--- + +## 🔧 SDK 使用示例 + +### JavaScript SDK + +```javascript +// 查询专业列表 +const queryParams = { + pageNum: 1, + pageSize: 10, + deptCategoryLike: 'zy-', + parentId: 102 +}; +const listResult = await listMajor(queryParams); + +// 新增专业 +const majorData = { + parentId: 102, + deptName: "计算机科学与技术", + deptCategory: "zy-001", + orderNum: 1, + status: "0" +}; +const addResult = await addMajor(majorData); + +// 修改专业 +majorData.deptId = 201; +majorData.deptName = "计算机科学与技术（本）"; +const updateResult = await updateMajor(majorData); + +// 删除专业 +const deleteResult = await delMajor(201); + +// 获取学院树 +const collegeTree = await getCollegeTree(); +``` + +--- + +## 🧪 测试用例 + +### 接口测试 + +```javascript +// Jest 测试示例 +describe('专业信息管理 API Tests', () => { + test('查询专业列表接口', async () => { + const response = await request(app) + .get('/system/dept/list?deptCategoryLike=zy-') + .set('Authorization', `Bearer ${token}`) + .expect(200); + + expect(response.body.code).toBe(200); + expect(response.body.data).toBeDefined(); + }); + + test('新增专业接口', async () => { + const majorData = { + parentId: 102, + deptName: "测试专业", + deptCategory: "zy-test", + orderNum: 1, + status: "0" + }; + + const response = await request(app) + .post('/system/dept') + .set('Authorization', `Bearer ${token}`) + .send(majorData) + .expect(200); + + expect(response.body.code).toBe(200); + expect(response.body.data.deptId).toBeDefined(); + }); +}); +``` + +--- + +## 🔄 版本历史 + +### v1.0.0 - 2025-12-26 + +- ✅ 初始版本发布 +- ✅ 完成基础 CRUD 接口 +- ✅ 实现学院树形菜单和专业列表联动 +- ✅ 支持专业的增删改查功能 + +--- + +## 📖 相关文档 + +- **数据库设计**：[数据库设计文档](../设计文档/database/) +- **业务需求**：[业务需求文档](../需求文档/) +- **二级学院管理**：[二级学院管理API](./二级学院管理API.md) +- **技术架构**：[技术架构文档](./技术架构/) +- **开发规范**：[开发规范文档](./开发规范/) + +--- + +## 📞 联系方式 + +**开发团队**：Cursor AI +**负责人**：Cursor AI +**邮箱**：无 +**文档维护**：实时更新，如有问题请及时反馈 + +--- + +**📌 重要提醒**： + +1. 所有接口都需要先登录获取 token +2. 请求头必须包含 `Authorization: Bearer {token}` +3. 专业类别编码必须以 "zy-" 开头 +4. 新增专业时必须选择所属的二级学院 +5. 删除操作会进行关联数据检查 +6. 左侧学院树点击后，右侧列表会筛选对应学院的专业 +7. 生产环境请使用 HTTPS 协议 diff --git a/docs/开发文档/API/二级学院管理API.md b/docs/开发文档/API/二级学院管理API.md new file mode 100644 index 00000000..70a13a80 --- /dev/null +++ b/docs/开发文档/API/二级学院管理API.md @@ -0,0 +1,540 @@ +# 二级学院管理 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 协议 diff --git a/web/src/api/xg/xsjcxx/classMsg/majormsg/index.ts b/web/src/api/xg/xsjcxx/classMsg/majormsg/index.ts new file mode 100644 index 00000000..f1f50ab2 --- /dev/null +++ b/web/src/api/xg/xsjcxx/classMsg/majormsg/index.ts @@ -0,0 +1,55 @@ +import request from '@/utils/request'; +import { AxiosPromise } from 'axios'; +import { MajorVO, MajorQuery, MajorForm } from './types'; + +// 查询专业列表 (dept_category 以 zy- 开头的) - 注意：此接口不支持分页，返回所有数据 +export const listMajor = (query?: MajorQuery) => { + return request({ + url: '/system/dept/list', + method: 'get', + params: { ...query, deptCategoryLike: 'zy-' } // 查询以 zy- 开头的专业 + }); +}; + +// 查询专业详细 +export const getMajor = (deptId: string | number): AxiosPromise => { + return request({ + url: '/system/dept/' + deptId, + method: 'get' + }); +}; + +// 新增专业 +export const addMajor = (data: MajorForm) => { + return request({ + url: '/system/dept', + method: 'post', + data: data + }); +}; + +// 修改专业 +export const updateMajor = (data: MajorForm) => { + return request({ + url: '/system/dept', + method: 'put', + data: data + }); +}; + +// 删除专业 +export const delMajor = (deptId: number | string) => { + return request({ + url: '/system/dept/' + deptId, + method: 'delete' + }); +}; + +// 获取二级学院树形结构 +export const getCollegeTree = () => { + return request({ + url: '/system/dept/list', + method: 'get', + params: { parentId: 101 } // 获取二级学院 + }); +}; diff --git a/web/src/api/xg/xsjcxx/classMsg/majormsg/types.ts b/web/src/api/xg/xsjcxx/classMsg/majormsg/types.ts new file mode 100644 index 00000000..9026f390 --- /dev/null +++ b/web/src/api/xg/xsjcxx/classMsg/majormsg/types.ts @@ -0,0 +1,54 @@ +/** + * 专业查询参数 + */ +export interface MajorQuery extends PageQuery { + deptName?: string; + deptCategory?: string; + parentId?: number; + deptCategoryLike?: string; + status?: string; +} + +/** + * 专业类型 + */ +export interface MajorVO extends BaseEntity { + id: number | string; + parentName: string; + parentId: number | string; + children: MajorVO[]; + deptId: number | string; + deptName: string; + deptCategory: string; + orderNum: number; + status: string; + delFlag: string; + ancestors: string; + menuId: string | number; +} + +/** + * 专业表单类型 + */ +export interface MajorForm { + parentName?: string; + parentId?: number | string; + children?: MajorForm[]; + deptId?: number | string; + deptName?: string; + deptCategory?: string; + orderNum?: number; + status?: string; + delFlag?: string; + ancestors?: string; +} + +/** + * 学院树节点类型 + */ +export interface CollegeTreeNode { + id: number | string; + label: string; + parentId: number | string; + children?: CollegeTreeNode[]; +} diff --git a/web/src/api/xg/xsjcxx/collegemsg/index.ts b/web/src/api/xg/xsjcxx/collegemsg/index.ts new file mode 100644 index 00000000..7deae077 --- /dev/null +++ b/web/src/api/xg/xsjcxx/collegemsg/index.ts @@ -0,0 +1,46 @@ +import request from '@/utils/request'; +import { AxiosPromise } from 'axios'; +import { CollegeVO, CollegeQuery, CollegeForm } from './types'; + +// 查询二级学院列表 (parent_id = 101) +export const listCollege = (query?: CollegeQuery) => { + return request({ + url: '/system/dept/list', + method: 'get', + params: { ...query, parentId: 101 } // 固定查询parent_id = 101的二级学院 + }); +}; + +// 查询二级学院详细 +export const getCollege = (deptId: string | number): AxiosPromise => { + return request({ + url: '/system/dept/' + deptId, + method: 'get' + }); +}; + +// 新增二级学院 +export const addCollege = (data: CollegeForm) => { + return request({ + url: '/system/dept', + method: 'post', + data: { ...data, parentId: 101 } // 固定设置parentId为101 + }); +}; + +// 修改二级学院 +export const updateCollege = (data: CollegeForm) => { + return request({ + url: '/system/dept', + method: 'put', + data: data + }); +}; + +// 删除二级学院 +export const delCollege = (deptId: number | string) => { + return request({ + url: '/system/dept/' + deptId, + method: 'delete' + }); +}; diff --git a/web/src/api/xg/xsjcxx/collegemsg/types.ts b/web/src/api/xg/xsjcxx/collegemsg/types.ts new file mode 100644 index 00000000..2b192964 --- /dev/null +++ b/web/src/api/xg/xsjcxx/collegemsg/types.ts @@ -0,0 +1,43 @@ +/** + * 二级学院查询参数 + */ +export interface CollegeQuery extends PageQuery { + deptName?: string; + deptCategory?: string; + status?: string; + parentId?: number; +} + +/** + * 二级学院类型 + */ +export interface CollegeVO extends BaseEntity { + id: number | string; + parentName: string; + parentId: number | string; + children: CollegeVO[]; + deptId: number | string; + deptName: string; + deptCategory: string; + orderNum: number; + status: string; + delFlag: string; + ancestors: string; + menuId: string | number; +} + +/** + * 二级学院表单类型 + */ +export interface CollegeForm { + parentName?: string; + parentId?: number | string; + children?: CollegeForm[]; + deptId?: number | string; + deptName?: string; + deptCategory?: string; + orderNum?: number; + status?: string; + delFlag?: string; + ancestors?: string; +} diff --git a/web/src/views/xg/xsjcxx/classmsg/collegemsg/index.vue b/web/src/views/xg/xsjcxx/classmsg/collegemsg/index.vue new file mode 100644 index 00000000..defd16c9 --- /dev/null +++ b/web/src/views/xg/xsjcxx/classmsg/collegemsg/index.vue @@ -0,0 +1,316 @@ + + + + + diff --git a/web/src/views/xg/xsjcxx/classmsg/majormsg/index.vue b/web/src/views/xg/xsjcxx/classmsg/majormsg/index.vue new file mode 100644 index 00000000..8380eb4d --- /dev/null +++ b/web/src/views/xg/xsjcxx/classmsg/majormsg/index.vue @@ -0,0 +1,499 @@ + + + + + + +