# 管理员端理论练习接口 本文档对应“管理员 → 教务管理 → 理论练习”一级列表、二级统计页面和个人详情弹框。 所有管理员接口继续使用 `/theoretical/practice` 前缀并要求有效管理员令牌。 ## 1. 数据库升级 上线接口前执行: ```text practical-business/src/main/resources/sql/theoretical_practice_statistics.sql ``` 脚本创建不可变作答记录表及统计索引,可重复执行。旧题库表只保存最后答案,无法可靠还原 历史作答次数和耗时,因此不回填旧数据;统计从新表产生第一条记录后开始。 ## 2. 一级页面分页 ### 2.1 等级筛选项 `GET /theoretical/practice/levels` 返回理论练习表中实际存在的全部非空等级,每项包含相同语义的 `value` 和 `label`。 页面应直接使用该接口渲染等级下拉框,不再从“工种 → 学年 → 等级 → 班级”导航树的 局部分支提取等级。这样历史班级缺少工种、跨学年或跨工种时都不会遗漏筛选项。 ```json { "code": 200, "data": [ {"value": "技能竞赛", "label": "技能竞赛"}, {"value": "污水四级", "label": "污水四级"}, {"value": "污泥五级", "label": "污泥五级"} ] } ``` ### 2.2 分页查询 `POST /theoretical/practice/page` ```json { "pageNum": 1, "pageSize": 10, "lev": "污水一级", "status": "ONGOING", "filterStartDate": "2026-07-01", "filterEndDate": "2026-07-31" } ``` - `status`:`PENDING`、`ONGOING`、`ENDED`,忽略大小写。 - 时间采用完整包含口径:练习开始时间不早于起始日,结束时间不晚于结束日当天。 - 返回仍为项目统一 `TableDataInfo`,并同时提供中文 `status` 和稳定的 `statusCode`。 - 状态统一为 `PENDING` / 未开始、`ONGOING` / 进行中、`ENDED` / 已结束。 - `ENDED` 同时包含自然到期和手动关闭,列表中均展示“已结束”。 ## 3. 一级页面全局统计 `GET /theoretical/practice/summary` ```json { "code": 200, "data": { "totalCount": 12, "ongoingCount": 4, "endedCount": 6 } } ``` 顶部数字始终统计全部练习,不随列表筛选条件变化。未开始练习只计入总数。 ## 4. 二级页面总体与知识点统计 `GET /theoretical/practice/{practiceId}/statistics/overview` 核心返回字段: | 字段 | 说明 | |---|---| | assignedStudentCount | 本期分配学员数,人均指标的分母 | | averageAnswerCount | 人均累计提交次数,保留两位小数 | | averageStudyDurationSeconds | 人均学习时长(秒) | | averageAccuracyRate | 正确提交数/全部提交数,百分比 | | activeStudentCount | 至少提交过一次答案的学员数 | | statisticsStartTime | 本期第一条新作答记录时间,无记录时为空 | | knowledgePoints | 知识点答题数、时长、正确率和掌握度 | ## 5. 二级页面学员分页 `POST /theoretical/practice/{practiceId}/statistics/students/page` ```json { "pageNum": 1, "pageSize": 10, "keyword": "张" } ``` 名单以 `theoretical_practice_student` 为准,未作答学员也会返回。主要字段包括 `answerCount`、`studyDurationSeconds`、`accuracyRate`、`masteryRate`、`statusCode`、 `statusLabel` 和 `lastAnswerTime`。 学员状态: - 无作答:`NOT_STARTED` / 未开始; - 正确率大于等于80%:`EXCELLENT` / 优秀; - 正确率大于等于60%:`GOOD` / 良好; - 其余:`NEEDS_IMPROVEMENT` / 待加强。 ## 6. 个人详情与Word报告 - `GET /theoretical/practice/{practiceId}/statistics/students/{studentId}` - `GET /theoretical/practice/{practiceId}/statistics/students/{studentId}/export` 详情返回个人累计指标和知识点能力列表,前端可用 `knowledgePoints[].masteryRate` 绘制雷达图。 导出接口返回 `.docx`,包含学员、班级、累计指标、知识点明细和数据更新时间。 ## 7. 学生答题接口接入 原路径保持不变:`POST /theoretical/practice/student/question/bank/update` ```json { "id": "题目ID", "actualChoice": "A", "requestId": "7d2630eb-c9d1-4dd1-a939-8d7b43fcf756", "durationSeconds": 42 } ``` - `requestId`:每次点击提交时新建、网络重试时复用,最长64字符。 - `durationSeconds`:当前题实际停留秒数,范围0到3600。 - 服务端从JWT确定学员,验证题目归属和唯一开放练习,并自行判定正确结果。 - 同一学员的相同 `requestId` 只记录一次;题库当前答案与历史记录在同一事务中提交。 ## 8. 统计口径 - 答题数:本期所有有效提交,重复作答累计。 - 正确率:正确提交数 ÷ 全部提交数。 - 掌握度:已答过的不同题目数 ÷ 当前学员本等级题库题目数。 - 人均答题数和人均时长:总量 ÷ 本期全部分配学员,未作答学员按0计算。 - 所有比例保留两位小数,零分母返回 `0.00`。