# 教师端“教学管理-我的课程”接口 所有接口都从 `Authorization` 解析当前用户并校验“教师”角色。请求中的历史字段 `userId`、`teacherId` 不参与数据权限判断,教师只能查询和点名本人负责的排课。 ## 1. 月历与统计 ### `POST /class/schedule/teacher` 请求体可为空;为空时默认当前自然月。自定义日期范围最多 62 天: ```json {"startDate":"2026-08-01","endDate":"2026-08-31","userId":"该值会被忽略"} ``` 响应继续使用旧版按天分组结构。`classSubjectList` 中每门课程增加: - `studentCount`:班级当前学员数; - `status`:`UPCOMING` 未开始、`PENDING` 待完成点名、`DONE` 已完成点名; - `verificationCode`:教师已经开始上课且签到会话仍为 `ACTIVE` 时返回六位签到码,否则不返回该字段; - `attendance`:应到、正常、迟到、缺勤、请假和出勤率。 课程结束后查询页面会幂等补写尚无记录的学员为 `ABSENT`,随后再计算状态。 ### `POST /class/schedule/teacher/detail` ```json {"date":"2026-08-19","teacherId":"该值会被忽略"} ``` 返回当天课程数量 `subjectNum` 和课程数组 `data`。日期必须严格使用 `yyyy-MM-dd`。 ### `GET /class/today/course/teacher` 返回当前教师今天的全部排课,字段和月历中的课程对象一致。 ### `POST /class/teacher/course/summary` 日期规则与月历接口相同,响应示例: ```json { "本月课时": 12, "本月课程": 12, "已完成课程": 7, "待完成课程": 5, "平均出勤率": 94 } ``` “本月课时”是旧客户端兼容键,与“本月课程”数值相同。平均出勤率只汇总已完成点名的 课程,按 `(正常 + 迟到) / 应到人数` 加权计算;请假计入应到但不计入到课。 ## 2. 课堂点名 1. `POST /attendance/teacher/course/{subjectId}/start`:到达计划开始时间后开始上课并取得验证码; 2. `GET /attendance/teacher/course/{subjectId}/roster`:读取完整名册和当前状态; 3. `PUT /attendance/teacher/status`:调整单名学员为 `NORMAL`、`LATE` 或 `ABSENT`; 4. `PUT /attendance/teacher/course/{subjectId}/roster`:事务化提交整班点名。 批量提交示例: ```json { "records": [ {"studentId":"190000000000000001","status":"NORMAL"}, {"studentId":"190000000000000002","status":"LATE"}, {"studentId":"190000000000000003","status":"ABSENT"} ] } ``` 请求必须包含班级内除已审批请假外的全部学员,不能重复、漏标或提交其他班级学员。 `LEAVE` 只能由请假审批模块产生,教师点名接口只读展示且数据库写入层会防止并发覆盖。 批量提交任一校验或写入失败时整次事务回滚。 ## 3. 数据库脚本 部署前执行 `sql/teacher_course.sql`。脚本可重复执行,仅确保教师日期索引、课程学员出勤唯一索引 和课程签到会话唯一索引;如果历史数据重复会明确报错并附带只读排查 SQL,不会自动删除数据。