# 管理员端学员成绩管理接口 管理端接口统一使用 `/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`。列表额外返回: - `paperAvailable`:只有学员已交卷、成绩已正式发布且个人试卷明细存在时为 `true`,前端据此 展示或启用“查看试卷”按钮。 - `paperUnavailableReason`:按钮不可用时返回“学员尚未交卷”“成绩尚未正式发布”或 “试卷明细不存在”,可直接作为禁用态提示;可以查看时返回 `null`。 ## 4. 学员详情与题目统计 - `GET /exam/admin/scores/exam-students/{examStudentId}/paper`:成绩明细列表“查看试卷”按钮的 推荐接口,只允许读取已交卷且正式发布的个人试卷。一次返回弹窗所需的学员、考试、试卷名称、 成绩、题目总数、答对/部分对/答错数量、加权正确率及完整逐题明细。理论考试返回 `theoryQuestions`;实训考试返回 `practiceItems`。 - `GET /exam/admin/scores/exam-students/{examStudentId}`:兼容旧客户端的详情地址,响应和校验与 上述 `/paper` 接口完全一致。 `correctRate` 按 `(答对数 + 部分对数 × 0.5) / 总题数 × 100` 计算并保留两位小数。理论试卷的 `sequence` 由后端按稳定题目顺序统一重编号为 `1..N`,避免历史空序号或字符串序号导致导航错乱。 实训结果兼容中文及英文的通过、部分通过和失败文本。 - `GET /exam/admin/scores/exams/{examId}/questions/statistics`:理论题返回满分、平均分、得分率、 答对人数和难度,`sequence` 为从 `1` 开始的全卷连续题号;实训题使用 `questionCode`,且实训协议没有每题满分,因此 `maxScore/scoreRate/difficulty` 为 `null`。 ## 5. Excel导出 - `GET /exam/admin/scores/exams/{examId}/export`:按人社局成绩汇总表模板导出。所选考试必须 已结束且已发布;服务端自动匹配同班级另一类型中最近一场已结束、已发布考试。找不到配对 考试时仍生成部分汇总表,缺少类型的人数为0,成绩列留空。 - `GET /exam/admin/scores/classes/{classId}/export`:导出班级历史考试汇总和所有正式学员成绩。 单场汇总表响应类型为 `application/vnd.ms-excel`,文件名为“班级名称_成绩汇总表.xls”。名单 取两场应考学员并集,缺考或未列入另一场名单时对应成绩留空并写入备注;实训项目按实际 编号与二级题目类型动态填充,二级题目类型为空时仅展示编号,不回退使用题目标题。超过模板 初始的5项时继续向右扩展,备注列同步顺延。受旧版 `.xls` 最多256列的格式限制,单次导出最多支持251个实训项目。每27名学员生成一张同版式分表, 序号跨分表连续。 班级历史导出继续返回 `.xlsx`。两类文件名均通过 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`必填,考试必须为实训,学员必须属于本场应考名单,汇总不得超过考试总分。 - 首次成功后进入教师待复核,不会自动对管理员成绩页或学员端发布。 - 忽略服务端主键和数组顺序后,内容完全相同的网络重试返回成功;任何变化均被拒绝,只能由教师复核调整。