# 管理员端学员成绩管理接口 管理端接口统一使用 `/exam/admin/scores` 前缀。每次请求都必须携带 `Authorization`,服务端从 JWT解析当前用户并校验 `phone_role.role_name=管理员`。本模块只提供查询和导出;评分与发布仍由 首席考评教师通过 `/exam/teacher/scores/review` 完成。 部署前依次执行已有 `sql/exam_management.sql`、`sql/exam_review.sql`,再执行 `sql/student_score_management.sql`。 ## 统一展示与成绩口径 - 考试创建成功后立即出现在成绩管理列表,`examStatus` 按时间实时返回 `UPCOMING / ONGOING / ENDED`。 - 未开始和进行中的考试允许查看考试概况、应考名单及交卷进度。 - 理论成绩必须同时满足 `exam.mark_flag=1`、`exam_student.mark_flag=1` 才是正式成绩。 - 实训成绩由仿真系统整份上报后进入待复核;首席考评教师确认发布后才设置上述发布标记。 - 待批阅场次可返回应考、实考人数,但平均分、合格率和个人分数为 `null`。 - 个人答题详情、题目统计和成绩导出仍要求对应成绩正式发布;统计和导出同时要求考试已结束。 - 合格率分母为已经实考且成绩正式发布的人数,缺考学员不计为不合格。 ## 1. 班级导航树 `GET /exam/admin/scores/tree?keyword=污水` 返回 `OCCUPATION → YEAR → LEVEL → CLASS` 四层节点。班级叶节点的 `classId` 用于后续请求。 ## 2. 全部考试分页 `POST /exam/admin/scores/exams/page` ```json { "pageNum": 1, "pageSize": 10, "classId": 10, "keyword": "期末", "type": "THEORY", "status": "PUBLISHED", "startDate": "2026-01-01", "endDate": "2026-12-31" } ``` `type` 支持 `THEORY/PRACTICE`,也兼容数据库中文值“理论/实训”;`status` 支持 `ALL/PENDING_REVIEW/PUBLISHED`。返回行中的 `examStatus` 是考试生命周期,`reviewStatus` 是 成绩发布状态,两者互不替代。 ## 3. 考试汇总与学员分页 - `GET /exam/admin/scores/exams/{examId}`:返回考试与班级信息、应考/实考、已发布人数、 平均分、合格人数和合格率。 - `POST /exam/admin/scores/exams/{examId}/students/page`:请求体支持 `pageNum`、`pageSize`、 `keyword` 和 `scoreBand`。 `scoreBand` 支持: - `ALL` - `EXCELLENT`:90分及以上 - `GOOD`:80~89.99分 - `PASS`:60~79.99分 - `FAIL`:60分以下 未发布考试仍返回应考学员和交卷状态,但 `score/grade/passed` 为 `null`。 ## 4. 学员详情与题目统计 - `GET /exam/admin/scores/exam-students/{examStudentId}`:只允许读取正式发布成绩。理论考试返回 `theoryQuestions`;实训考试返回 `practiceItems`。 - `GET /exam/admin/scores/exams/{examId}/questions/statistics`:理论题返回满分、平均分、得分率、 答对人数和难度;实训协议没有每题满分,因此 `maxScore/scoreRate/difficulty` 为 `null`。 ## 5. Excel导出 - `GET /exam/admin/scores/exams/{examId}/export`:导出单场已发布成绩。 - `GET /exam/admin/scores/classes/{classId}/export`:导出班级历史考试汇总和所有正式学员成绩。 响应类型为 `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`,文件名通过 RFC 5987 UTF-8编码。未发布考试禁止导出。 ## 6. 仿真实训完整成绩上报 `POST /fz/grades/receive` ```json [ { "examId": 1001, "userId": "1900000000000000201", "code": "STEP-01", "lev": "污水一级", "startTime": "2026-08-17 09:00:00", "submissionTime": null, "title": "启动前安全检查", "type": "3", "text": "已完成检查", "result": "通过", "file": null, "score": 10 } ] ``` - 一次请求只能包含同一`examId + userId`的一份完整成绩,`code`不得重复。 - `examId/userId/code/score`必填,考试必须为实训,学员必须属于本场应考名单,汇总不得超过考试总分。 - 首次成功后进入教师待复核,不会自动对管理员成绩页或学员端发布。 - 忽略服务端主键和数组顺序后,内容完全相同的网络重试返回成功;任何变化均被拒绝,只能由教师复核调整。