all-project/docs/开发文档/API/班级信息管理API.md

班级信息管理 API

模块名称：classMsg / 班级信息
基础路径：/classMsg/classMsg
更新时间：2026-09-01

模块功能

班级基础信息的增删改查、状态批量变更、所在校区维护（含批量设置），以及 Excel 批量导入（模板含字典下拉、学院-专业联动下拉、校区下拉）。

所在校区（2026-09-01）

• 数据字段：campusId / campusName（选填，关联【校区信息】xg_dorm_campus）
• 列表查询支持 campusId 筛选
• 新增/修改可选择或清空校区；服务端按校区 ID 回填名称
• 历史班级补齐：列表多选 →「批量设置校区」

批量设置校区

• URL：PUT /classMsg/classMsg/campus/batch
• Body：

{
  "ids": [1, 2, 3],
  "campusId": 1946815553291304962
}

• 说明：ids、campusId 均必填；校区须存在且未删除；统一写入 campus_id + campus_name

导入相关接口

1. 下载导入模板

• URL：POST /classMsg/classMsg/importTemplate
• 说明：生成带下拉校验的 Excel 模板
• 模板列：

列名	填写方式	说明
学院	下拉（联动）	仅显示学院名称，请从下拉选择；列已加宽
专业	下拉（联动）	随学院变化，仅显示专业名称；列已加宽
班级名称	文本	必填；同时作为班级代码写入系统
学历层级	字典下拉	zsjy_education_level 中文标签；列已加宽
年级	文本	如当前年份
入学年份	数字	如当前年份
学制(年)	下拉	常见值 2/3/4/5/6
毕业年份	公式自动计算	Excel 公式：入学年份+学制；导入时同样按此规则计算
是否已毕业	字典下拉	is_graduation（未毕业/已毕业）
班级教室位置	文本	可选
所在校区	下拉	选填；选项来自【校区信息】校区名称；按名称解析写入
班级状态	字典下拉	xg_class_status（正常/暂停/毕业/解散）
班主任	文本（姓名）	选填；按教职工姓名精确匹配。唯一命中才写入；未匹配或多人同名则跳过，不影响班级保存
班级描述	文本	可选
备注信息	文本	可选

• 注意：
  • 模板首行示例数据以「示例」开头，导入时会自动跳过
  • 学院、专业、校区、字典项请务必从下拉框选择，避免手填错误
  • 所在校区留空则不写入；名称不存在或不唯一则该行失败
  • 班主任匹配失败不会导致该行班级导入失败，可事后在列表中单独设置
  • 导入为仅新增；历史班级补校区请用「批量设置校区」

2. 导入班级数据

• URL：POST /classMsg/classMsg/importData
• Content-Type：multipart/form-data
• 参数：file（Excel 文件）
• 成功响应：R，msg 为导入成功明细（HTML，含班主任匹配提示）
• 失败响应：抛出业务异常，msg 含失败行号与原因
• 处理逻辑：
  1. 解析学院/专业名称，并校验专业属于所选学院
  2. 字典中文标签自动转换为字典值
  3. 班级名称作为 classCode / className，重复则该行失败
  4. 毕业年份按 入学年份 + 学制 自动计算
  5. 可选解析所在校区名称并写入 campusId/campusName
  6. 调用既有新增逻辑，同步创建对应 sys_dept 班级节点
  7. 班主任按姓名匹配有效教职工：0 人或多人 → 不写班主任；1 人 → 写入并同步关联/角色

其他已有接口（摘要）

接口	方法	路径
分页列表	GET	/classMsg/classMsg/list
详情	GET	/classMsg/classMsg/{id}
新增	POST	/classMsg/classMsg
修改	PUT	/classMsg/classMsg
删除	DELETE	/classMsg/classMsg/{ids}
更新状态	PUT	/classMsg/classMsg/status
批量更新状态	PUT	/classMsg/classMsg/status/batch
批量设置校区	PUT	/classMsg/classMsg/campus/batch
导出	POST	/classMsg/classMsg/export
我作为班主任的班级	GET	/classMsg/classMsg/myClassListAsTeacher

前端入口

• 页面：web/src/views/xg/xsjcxx/classmsg/classMsg/index.vue
• 操作：工具栏「导入」→ 下载模板 / 上传 Excel；「批量设置校区」
• 数据库脚本：docs/数据库脚本/2026-09-01-xg_class_msg-add-campus.sql