# 管理员端课程管理接口 接口统一使用 `/class/subject/admin` 前缀,所有请求都必须携带 `Authorization`。服务端从 JWT解析当前用户并校验管理员角色,不接受客户端提交管理员用户ID。 部署前依次执行: 1. `src/main/resources/sql/class_management.sql` 2. `src/main/resources/sql/course_management.sql` 课程脚本会补充 `class_subject.schedule_group_id`、审计列和查询索引。组内课程仍分别 保存为独立 `class_subject` 记录,因此原有签到、请假和评价表继续使用课程 `id`,不需要迁移 任何业务外键。旧课程会回填为独立排课组,避免把同日历史记录错误合并。 ## 1. 班级导航树 `GET /class/subject/admin/tree?keyword=污水` 返回 `OCCUPATION → YEAR → LEVEL → CLASS` 四层节点,结构与班级管理树一致。班级叶节点的 `classId` 用于后续课程查询和新增请求。 ## 2. 表单选项 `GET /class/subject/admin/options` 返回有效授课教师和固定课程类型:`理论`、`实训`、`考核`。教师选项的 `value` 是用户ID, `label` 是姓名,保存时必须提交ID,不能提交教师姓名。 ## 3. 查询班级课程表 `GET /class/subject/admin/classes/{classId}` 可选参数:`startDate=2026-09-01&endDate=2026-09-30`。 响应同时保留两种数据结构: - `courses`:独立课程平铺数组,兼容旧调用方; - `schedules`:新版页面使用的排课组数组,同一行的同日课程位于 `items` 中。 ```json { "classId": 10, "className": "污水处理一级一班", "termName": "2026 秋", "studentCount": 35, "courseCount": 2, "scheduleCount": 1, "totalHours": 4.0, "courses": [ { "id": 1001, "scheduleGroupId": "1900000000000000100", "date": "2026-09-08", "week": "周二", "period": "AM", "subjectTimes": 2, "timeFrames": ["09:00-10:20", "10:40-12:00"], "subjectHour": 2.0, "subjectName": "水污染知识", "teacherId": "1900000000000000001", "teacherName": "王建国", "type": "理论" } ], "schedules": [ { "scheduleGroupId": "1900000000000000100", "classId": 10, "date": "2026-09-08", "week": "周二", "subjectTimes": 4, "totalHours": 4.0, "items": [ {"id": 1001, "period": "AM", "subjectName": "水污染知识"}, {"id": 1002, "period": "PM", "subjectName": "污水处理工艺"} ] } ] } ``` `period` 取值: - `AM`:全部时段均在12:00前结束; - `PM`:全部时段均从12:00或之后开始; - `ALL_DAY`:单个时段跨越12:00,或多个时段同时分布在上午和下午。 ## 4. 批量新增课程 `POST /class/subject/admin/batch` 新版页面在批次顶部统一选择课程类型,每行分别选择上课日期。同一请求中日期相同的课程行 会自动获得同一个 `scheduleGroupId`。 ```json { "classId": 10, "type": "理论", "courses": [ { "date": "2026-09-08", "subjectTimes": 2, "timeFrames": ["09:00-10:20", "10:40-12:00"], "subjectHour": 2.0, "subjectName": "水污染知识", "teacherId": "1900000000000000001", "location": "A栋302", "remark": "第一章" }, { "date": "2026-09-08", "subjectTimes": 2, "timeFrames": ["13:00-14:20", "14:40-16:00"], "subjectHour": 2.0, "subjectName": "污水处理工艺", "teacherId": "1900000000000000002", "location": "A栋302" } ] } ``` 兼容规则:旧客户端可以不传批次 `type`,改为在每个课程内提交 `type`;如果两处同时提交, 值必须一致。 校验规则: - 单次至少1节、最多100节;任意行失败时整个事务回滚,错误消息包含“第N节课程”; - 日期必须位于班级培训起止日期内,星期由服务端计算; - 课次允许0~40,课时允许0~16并以0.5递增; - 每行允许1~8个时段,格式为 `HH:mm-HH:mm`,兼容 `~`、`—`、`–`、`→`; - 同一行允许单个时段跨越12:00,也允许多个时段同时分布在上午和下午; - 同一日期可提交多条课程,课程之间按实际时段判断冲突; - 同班级或同教师的时段不能重叠,首尾相接不算冲突; - 课程名称最多100字,地点最多255字,备注最多1000字。 成功后返回刷新后的完整班级课程表。 ## 5. 编辑整行排课 `PUT /class/subject/admin/schedules/{scheduleGroupId}` 新版编辑弹窗使用本接口一次保存同一排课组内的课程,最多100节。组级日期只提交一次; 已有课程必须回传 `id`,新增课程不传 `id`。请求未包含的旧课程表示删除。 ```json { "date": "2026-09-09", "courses": [ { "id": 1001, "subjectTimes": 2, "timeFrames": ["09:00-10:20", "10:40-12:00"], "subjectHour": 2.0, "subjectName": "水污染知识", "teacherId": "1900000000000000001", "location": "A栋302", "type": "理论", "remark": "第一章" }, { "subjectTimes": 2, "timeFrames": ["13:00-14:20", "14:40-16:00"], "subjectHour": 2.0, "subjectName": "污水处理工艺", "teacherId": "1900000000000000002", "location": "A栋302", "type": "理论" } ] } ``` 服务端在一个事务内完成更新、插入和删除,并尽量保留已有课程ID。已产生签到、签到场次、 请假或评价的课程允许原样回传,但不能修改或删除;改变组日期也会被视为修改组内每条课程。 成功后返回刷新后的单个排课组。 ## 6. 与同班已有课次对调 `POST /class/subject/admin/schedules/{scheduleGroupId}/swap` 请求提交 `targetScheduleGroupId`、`sourcePeriod` 和 `targetPeriod`;两个期间只支持 `AM`(上午)或 `PM`(下午)。源、目标排课组必须属于同一班级。服务端只对调选中的半天,课程名称、授课教师、 地点、类型和备注随该半天课程移动;两组均记录“已调课”和对方组ID,不再采集原因与说明。 历史全天课程会在事务内拆为上午、下午两条后再对调;若该课程已有签到、请假或评价数据,服务端 拒绝拆分并返回明确提示,避免破坏既有业务引用。成功后返回交换后的两个排课组。 ## 7. 兼容的单课程编辑与删除 - `PUT /class/subject/admin/{courseId}`:保留旧单课程编辑接口,同时执行时段和冲突校验; - `DELETE /class/subject/admin/{courseId}`:删除没有签到、请假或评价数据的独立课程。 ## 8. 导出课程表 `GET /class/subject/admin/classes/{classId}/export` 支持与列表相同的日期范围参数,返回与导入参考文件一致的 `.docx` 课程安排表;同一排课组按 标准七列表格合并日期、课次、时段和课时,上午、下午课程及教师按原模板分行展示。 ## 9. 从Word课程安排表导入 `POST /class/subject/admin/classes/{classId}/import`,使用`multipart/form-data`上传`file`,仅支持 `.docx`且文件不超过10MB。模板表头必须包含日期、课次、时段、课时、课程和授课教师。 导入规则: - 月日使用目标班级的培训年度补全年份,教师姓名必须唯一匹配有效教师账户; - 课程名含“理论”时导入为理论课,含“实操/实训”时导入为实训课,含“考核/考试”时导入为考核; - 课程名称等于“单位实训”的行直接跳过,不校验该行日期和教师,也不生成课程记录; - 对“上午:1班,下午:2班”一类分班备注,按目标班级名称中的班号选择上午或下午时段, 并按选中时段占比折算课次和课时; - 全部非跳过行仍复用批量新增的教师、时段冲突及事务校验,任一行失败时整批不写入。 响应返回`importedCount`、`skippedUnitTrainingCount`以及刷新后的完整`detail`课程表。