server/training-system
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b20da3cd063c72579ddaf7860db2be25837c04b8
training-system/training/context/03-功能模块/04-考试模块.md
tony b20da3cd06 2026-05-12
2026-05-12 12:24:11 +08:00

11 KiB
Raw Blame History

考试模块（exam）

证据来源：[SRC-FEAT-01] [SRC-FEAT-02] [SRC-SQL-01] [SRC-API-01] [SRC-CODE-01：module/exam/]

1. 模块定位

  • 模块目标：管理从出题到考试全链路：题目→试卷→考试→作答记录，支持在线作答、自动判分、成绩排名。
  • 解决问题：替代纸质考试，提升出卷效率（自动组卷），实现客观题自动判分，并对考试行为（时间窗口、次数限制、超时交卷）进行严格管控。

2. 功能清单

[SRC-FEAT-01：模块三/四/五] [SRC-API-01：4.4 在线考试接口]

功能名称 功能描述 输入 输出 依赖模块
题目分类管理 按分类管理题目，多级目录，按部门隔离 QuestionCategoryDTO QuestionCategoryVO system
题目 CRUD 创建/修改/删除题目，支持单选/多选/判断三种题型，必须填写解析 QuestionDTO（type, content, options, answer, analysis） QuestionVO -
题目状态管理 草稿→发布→下架，下架前检查引用 questionId, action - -
手动组卷 讲师从题库手动选题，配置每题分值 PaperDTO（title, questions[]） PaperVO -
自动组卷 按规则（单选X题+多选Y题+判断Z题）随机抽题 AutoPaperDTO（规则配置） PaperVO -
试卷配置 设置总分、各题分值、考试时长、及格分 PaperDTO PaperVO -
试卷预览 组卷后预览试卷效果（随机题目顺序） paperId 完整试卷预览 -
试卷状态管理 草稿→发布→下架 paperId, action - -
创建考试 选择试卷，设置考试名称、时间窗口、最大次数 ExamQueryDTO + ExamTarget ExamVO -
指定考试对象 指定部门/小组/个人参加考试 exam_id, target_type, target_id[] - system
发布考试 将考试状态从 NOT_STARTED 转为 IN_PROGRESS（时间到自动） examId - -
学员-我的考试列表 查询分配给当前学员的考试（在时间窗口内） - PageResult<ExamVO + 我的记录> auth
学员-开始考试 校验资格，创建 exam_record，返回试题 examId 试题 + 时长 + recordId -
学员-断点续考 恢复进行中的考试记录，返回已保存答案 examId 试题 + 已保存答案 + 剩余时间 -
学员-保存答案 每30秒自动保存答案（增量保存） recordId, answers(JSON) - -
学员-提交试卷 自动判分，保存成绩，返回排名+解析 recordId, answers(JSON) 成绩 + 排名 + 答案解析 -
超时自动交卷 定时任务每分钟扫描超时记录，系统代提交 @Scheduled - -
查看考试结果 查看某次考试的详细成绩和答案解析 recordId ExamResultVO -
成绩/排名查询 讲师查看某考试的所有学员成绩 examId PageResult<成绩列表> -

3. 核心逻辑

3.1 业务规则

[SRC-FEAT-01：4.3 考试规则] [SRC-API-01：5.2/5.3]

题型规则：

  • 单选题（SINGLE=0）：options 为 JSON 数组，answer 为单字母（A/B/C/D）
  • 多选题（MULTIPLE=1）：answer 为多字母组合（如"AB"/"BCD"），按字母排序存储
  • 判断题（JUDGE=2）：options 为空，answer 为"T"（正确）或"F"（错误）
  • 每道题必须填写 analysis（答案解析），否则不允许发布

考试时间窗口：

  • 只有在 exam.start_time ≤ NOW() ≤ exam.end_time 时，学员才能进入考试
  • 考试到期后，exam.status 自动（或手动）变为 ENDED

次数限制：

  • 达到 max_attempts 后，学员不可再次开始考试
  • 历史成绩取最高分作为最终成绩
  • 每次考试创建 exam_record.attempt_no = 历史次数 + 1

自动判分规则：

  • 仅客观题（单选/多选/判断）自动判分
  • 单选/判断：答案完全匹配得满分
  • 多选：全部选项匹配（顺序无关）得满分；部分正确得 0 分（V1 不分项给分）
  • 总分 = 各题得分之和

超时自动交卷：

  • @Scheduled(cron="0 */1 * * * ?") 每分钟扫描
  • 查询：ex_exam_record.status=IN_PROGRESS 且 start_time + paper.duration 分钟 < NOW()
  • 使用乐观锁（version 字段）防止与用户主动交卷并发冲突 [SRC-API-01：5.2]

排名计算：

  • 计算时机：用户交卷后立即计算本次提交对应的排名
  • 统计范围：同一 exam_id 下，所有 status=SUBMITTED 记录，取每用户最高分
  • 排名规则：DENSE_RANK() OVER (ORDER BY MAX(score) DESC, MIN(submit_time) ASC)（同分按提交时间早排前）[SRC-API-01：5.3]

题目顺序：

  • 自动组卷时，返回给学员的题目顺序随机打乱（前端处理或后端随机返回）

3.2 校验逻辑

校验项 规则 失败响应
题目 analysis 必填 发布时 analysis 不可为空 400：请填写答案解析后再发布
开始考试-时间窗口 NOW() 在 [start_time, end_time] 范围内 400：考试尚未开始 / 考试已结束
开始考试-次数限制 已有考试记录数 < max_attempts 400：已达到最大考试次数
开始考试-状态 exam.status = IN_PROGRESS（1） 400（状态不符）
开始考试-进行中记录 若已有 IN_PROGRESS 记录，返回续考而非新建 自动转入断点续考流程
答案格式 多选题答案字母需排序后匹配 自动处理，不返回错误
超时交卷并发 乐观锁冲突时（用户已提交），忽略定时任务提交 静默忽略 OptimisticLockException
试卷引用保护 已被考试引用的试卷下架前需确认警告 400 + 警告 + 引用考试数量
题目引用保护 已被试卷引用的题目下架前需确认警告 400 + 警告 + 引用试卷数量

3.3 状态流转

内容状态（题目/试卷）：

stateDiagram-v2
    [*] --> DRAFT : 创建
    DRAFT --> PUBLISHED : 发布（题目需有 analysis）
    PUBLISHED --> OFFLINE : 下架（引用保护确认）
    OFFLINE --> PUBLISHED : 重新上架
    DRAFT --> [*] : 逻辑删除

考试状态：

stateDiagram-v2
    [*] --> NOT_STARTED : 创建考试（start_time 未到）
    NOT_STARTED --> IN_PROGRESS : 到达 start_time（自动或手动）
    IN_PROGRESS --> ENDED : 到达 end_time（自动或手动结束）
    ENDED --> [*] : 逻辑删除

考试记录状态：

stateDiagram-v2
    [*] --> IN_PROGRESS : 学员点击"开始考试"创建记录
    IN_PROGRESS --> SUBMITTED : 学员交卷（submit_source=USER）
    IN_PROGRESS --> SUBMITTED : 定时任务超时（submit_source=SYSTEM_TIMEOUT）
    SUBMITTED --> [*] : 永久保留

4. 数据结构

[SRC-SQL-01：三、考试模块]

4.1 涉及数据表（7张）

ex_question_category：题目分类（同知识库分类结构，按 department_id 隔离）

ex_question

字段 类型 说明
id BIGINT 主键
type TINYINT 0-单选 / 1-多选 / 2-判断
content TEXT NOT NULL 题干
options JSON 选项数组（判断题为 NULL）
answer VARCHAR(50) NOT NULL 正确答案（单选/判断单字母，多选合并字母）
analysis TEXT 答案解析（发布前必填）
category_id BIGINT 所属分类
department_id BIGINT NOT NULL 部门隔离键
status TINYINT 0-草稿 / 1-发布 / 2-下架
creator_id BIGINT NOT NULL 创建人

ex_paper

字段 类型 说明
id BIGINT 主键
title VARCHAR(200) NOT NULL 试卷标题
total_score INT DEFAULT 100 总分
duration INT DEFAULT 60 考试时长（分钟）
pass_score INT DEFAULT 60 及格分
department_id BIGINT NOT NULL 部门隔离键
status TINYINT 0-草稿 / 1-发布 / 2-下架

ex_paper_question

字段 类型 说明
paper_id BIGINT NOT NULL 试卷ID
question_id BIGINT NOT NULL 题目ID
score INT DEFAULT 5 该题分值
sort_order INT 排序（大题号顺序）

ex_exam

字段 类型 说明
id BIGINT 主键
title VARCHAR(200) NOT NULL 考试标题
paper_id BIGINT NOT NULL 关联试卷
start_time / end_time DATETIME 时间窗口
max_attempts INT DEFAULT 1 最大考试次数
department_id BIGINT NOT NULL 部门隔离键
status TINYINT 0-未开始 / 1-进行中 / 2-已结束

ex_exam_target

字段 类型 说明
exam_id BIGINT NOT NULL 考试ID
target_type TINYINT 0-部门 / 1-小组 / 2-个人
target_id BIGINT NOT NULL 对应 dept/group/user 的ID

ex_exam_record（含 V1.0.1 扩展字段）

字段 类型 说明
id BIGINT 主键
exam_id BIGINT NOT NULL 考试ID
user_id BIGINT NOT NULL 学员ID
attempt_no INT NOT NULL 第几次考试
score INT 得分
passed TINYINT 0-未通过 / 1-通过
start_time DATETIME NOT NULL 开始时间
submit_time DATETIME 提交时间
answers JSON 答题详情
status VARCHAR(20) IN_PROGRESS / SUBMITTED
last_save_time DATETIME 最后保存时间
version INT DEFAULT 0 乐观锁版本号
submit_source VARCHAR(20) USER / SYSTEM_TIMEOUT

4.2 数据关联

  • ex_paper_question.paper_id → ex_paper.id
  • ex_paper_question.question_id → ex_question.id
  • ex_exam.paper_id → ex_paper.id
  • ex_exam_target 多态关联：target_type=0 → sys_department.id；=1 → sys_group.id；=2 → sys_user.id
  • ex_exam_record.exam_id → ex_exam.id；user_id → sys_user.id

5. 对外接口

[SRC-API-01：4.4]

API 名称 方法 路径 权限
题目分类 CRUD GET/POST/PUT/DELETE /api/exam/question-category/** LECTURER/ADMIN
题目 CRUD GET/POST/PUT/DELETE /api/exam/question/** LECTURER/ADMIN
试卷 CRUD + 自动组卷 GET/POST/PUT/DELETE /api/exam/paper/** + /api/exam/paper/auto LECTURER/ADMIN
考试 CRUD GET/POST/PUT/DELETE /api/exam/** LECTURER/ADMIN
我的考试列表 GET /api/student/exam STUDENT
考试详情 GET /api/student/exam/{id} STUDENT
开始考试 POST /api/student/exam/{id}/start STUDENT
断点续考 GET /api/student/exam/{id}/continue STUDENT
保存答案 POST /api/student/exam/{id}/save STUDENT
提交试卷 POST /api/student/exam/{id}/submit STUDENT
查看考试结果 GET /api/student/exam/record/{recordId} STUDENT

6. 异常与边界处理

场景 处理方式
学员在时间窗口外访问考试 400 + 明确提示是"未开始"还是"已结束"
次数用完后再次开始 400：已达最大考试次数，如有异议请联系讲师
交卷时 exam_record 已是 SUBMITTED（并发/重复提交） 乐观锁冲突或状态判断，幂等返回已有成绩，不重复判分
定时任务超时提交时用户同时提交 乐观锁 version 冲突，定时任务忽略，用户提交成功
试卷总分与题目分值之和不一致 [ASSUMPTION] PRD 未明确，建议前端组卷时实时计算并提示差额
自动组卷时题库数量不足 400：题库中相应题型数量不足，请手动添加题目或降低要求
学员中途关闭浏览器 answers 按最后一次 save 记录恢复，重新进入走断点续考流程