# 管理员端课程管理接口 接口统一使用 `/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`:仅用于兼容历史跨上午、下午记录,新写接口不接受此类型。 ## 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}` 新版编辑弹窗使用本接口一次保存上午、下午课程。组级日期只提交一次;已有课程必须回传 `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. 兼容的单课程编辑与删除 - `PUT /class/subject/admin/{courseId}`:保留旧单课程编辑接口,同时执行期间和冲突校验; - `DELETE /class/subject/admin/{courseId}`:删除没有签到、请假或评价数据的独立课程。 ## 7. 导出课程表 `GET /class/subject/admin/classes/{classId}/export` 支持与列表相同的日期范围参数,返回带UTF-8 BOM的CSV。上午、下午课程按独立行输出,并包含 排课组ID和 `AM/PM/ALL_DAY` 期间,确保不同课程名或教师的信息不会在导出时丢失。