# 教师端成绩管理接口 页面路径为“教师端 → 智能考评 → 成绩管理”,接口统一使用 `/exam/teacher/scores` 前缀。所有请求必须携带 `Authorization`。服务端从 JWT 解析当前 用户并校验“教师”角色,教师 ID 不允许由前端传入;所有考试查询还会校验 `exam.chief_id` 等于当前教师 ID。 本模块只读取现有 `exam`、`exam_student`、`class` 和 `user` 表。现有数据库脚本已经 提供 `idx_exam_chief_time` 与 `idx_exam_student_exam_user` 索引,因此本功能无数据库结构 变更,不需要执行新增迁移脚本。 ## 统计口径 - 页面展示当前教师担任主考的考试;阅卷成绩发布后立即展示,未发布考试则须在计划结束后展示。 - 应考人数:该场考试全部 `exam_student` 记录数。 - 实考人数:`exam_student.submit = 1` 的人数。 - 最高分、最低分、平均分:只统计考试与学员成绩都已发布、已交卷且成绩非空的记录,平均分保留一位小数。 - 及格率:达到该场 `exam.pass_score` 的正式成绩人数 ÷ 正式成绩人数,保留两位小数。 - 没有正式成绩时,最高分、最低分、平均分和及格率均返回 `null`,不会返回误导性的零。 ## 1. 班级筛选选项 `GET /exam/teacher/scores/classes` 只返回当前教师担任主考且存在成绩管理可见考试的班级;已发布考试不再受计划结束时间限制: ```json { "code": 200, "data": [ {"classId": 12, "className": "净化1班"}, {"classId": 15, "className": "净化2班"} ] } ``` 前端的“全部班级”不需要对应数据库记录,查询考试时不传 `classId` 即可。 ## 2. 考试成绩分页列表 `POST /exam/teacher/scores/exams/page` ```json { "pageNum": 1, "pageSize": 10, "keyword": "月考", "classId": 12, "status": "ALL" } ``` `keyword` 和 `classId` 均可省略。`status` 支持 `ALL/PENDING_REVIEW/PUBLISHED`,默认 `ALL`。返回项目统一 `TableDataInfo`,`rows` 中每项结构如下: ```json { "examId": 101, "classId": 12, "examName": "污泥脱水工艺月考", "examType": "实训", "className": "净化1班", "examTime": "2026-08-10 09:00:00", "duration": 90, "totalScore": 100, "passScore": 60, "expectedCount": 32, "actualCount": 31, "reviewStatus": "PUBLISHED", "published": true, "publishedScoreCount": 31, "highestScore": 96, "lowestScore": 52, "averageScore": 81.3, "passRate": 93.55 } ``` 默认按考试时间、考试 ID 倒序;页码默认 1,每页默认 10 条,最多 100 条。 ## 3. 单场考试汇总 `GET /exam/teacher/scores/exams/{examId}` 返回结构与考试列表行一致,用于成绩详情页头部。待批阅且已经结束的考试允许查看汇总和 应考学员,但未发布分数不会返回;已发布考试可立即查看,不必等待计划时长结束。考试不 存在、不是当前教师主考或尚不可见时,统一提示 “考试不存在或无权访问”,避免通过 ID 探测其他考试。 ## 4. 应考学员成绩分页 `POST /exam/teacher/scores/exams/{examId}/students/page` ```json { "pageNum": 1, "pageSize": 10, "keyword": "张三" } ``` 关键字同时匹配学员姓名和身份证号。返回全部应考学员,缺考人员也会出现在列表中: ```json { "examStudentId": 9001, "examId": 101, "classId": 12, "studentId": "student-1", "studentName": "张三", "idCard": "310000********0001", "className": "净化1班", "examName": "污泥脱水工艺月考", "examType": "实训", "submitted": true, "published": true, "score": 88.5, "grade": "良好", "passed": true, "answerTime": "2026-08-10 10:12:30", "duration": "72分钟" } ``` 缺考人员的 `submitted`、`published` 为 `false`,`score`、`grade`、`passed` 为 `null`。 ## 5. 导出单场考试成绩 `GET /exam/teacher/scores/exams/{examId}/export` 响应类型为 `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`,文件名为 “考试名称_成绩单.xlsx”。导出不受页面关键字和分页影响,包含全部应考学员;缺考人员 标记为“缺考”且成绩单元格留空。前端应按二进制 Blob 接收响应,并优先从 `Content-Disposition` 读取 UTF-8 文件名。待批阅考试禁止导出。 ## 6. 批阅接口 批阅接口统一位于 `/exam/teacher/scores/review`: - `POST /tasks/page`:分页查询当前教师的待批阅/已完成任务。 - `POST /students/page`:分页查询某场考试已交卷学员。 - `GET /students/{examStudentId}/paper`:获取理论答题或实训项目明细。 - `PUT /students/{examStudentId}/scores`:暂存主观题或实训项目评分。 - `PUT /tasks/{examId}/publish`:校验评分完整性并发布整场成绩。 - `GET /students/{examStudentId}/history`:查询评分追溯记录。 所有接口均从 JWT 获取当前用户,先校验“教师”角色,再校验考试 `chief_id` 归属。管理员 成绩管理 `/exam/admin/scores` 仍只有查询和导出,不提供评分、重评分或发布接口。