server/training-system

Fork 0

Files

tony b20da3cd06 2026-05-12

2026-05-12 12:24:11 +08:00

26 KiB

Raw Permalink Blame History

学员端功能需求文档

版本：V1.0.1 创建日期：2026-01-15 更新日期：2026-01-15 状态：✅ 已批准（Supervisor 复审通过）

版本更新记录

V1.0.1 (2026-01-15)

根据Supervisor审查意见修订：

修订项	修订内容
知识学习入口	补充培训任务学习场景、返回逻辑、来源区分
断点续考机制	补充定时任务策略、超时判定规则、并发处理
排名计算规则	明确计算时机、统计范围、口径定义
学习时长防刷	新增活跃检测机制
数据表设计	km_knowledge_progress 新增 department_id 字段
页面路径	调整为复用现有路径，按角色控制
解析显示策略	明确交卷后立即显示解析
非功能需求	补充可测试的性能指标

一、概述

1.1 目标用户

角色：学员（STUDENT）
人数：约450人
入口：PC浏览器（与管理端共用系统，按角色显示不同菜单）

1.2 核心目标

为学员提供便捷的在线学习平台，支持知识学习、在线考试、培训计划跟踪，帮助学员提升专业技能。

二、功能模块总览

模块	功能点	优先级
工作台	学习概览、待办事项	P0
知识学习	知识浏览、学习进度、时长统计	P0
在线考试	考试列表、在线答题、断点续考、成绩排名	P0
我的培训	培训计划、进度跟踪、完成判定	P0
个人中心	学习记录、考试记录、证书（预留）	P1

三、详细功能需求

3.1 工作台（首页）

用户故事

作为学员，我希望登录后看到学习概览和待办事项，以便快速了解学习状态和接下来要做的事。

功能清单

功能项	说明
学习统计卡片	显示：待学习课程数、待完成考试数、培训进度百分比
我的培训计划	列表展示分配给我的培训计划（最多显示5条），显示进度
待完成考试	列表展示待完成的考试（最多显示5条），显示截止时间
快捷入口	点击可直接进入对应详情页

验收标准

登录后默认进入工作台页面
统计数据实时准确（待学习=未完成的必修知识数，待考试=未通过的必考考试数）
培训进度百分比 = 已完成必修项 / 总必修项 × 100%
点击培训计划可跳转到计划详情
点击考试可跳转到考试页面
只显示"进行中"状态的培训计划和处于"时间窗口内"的考试

3.2 知识学习

用户故事

作为学员，我希望浏览本部门的知识库，学习文档和视频，并能看到自己的学习进度。

功能清单

功能项	说明
知识分类导航	左侧树形结构展示知识分类
知识列表	按分类筛选，显示知识标题、类型、学习状态
知识详情/预览	文档在线预览、视频在线播放
学习进度记录	记录学习完成状态、学习时长
强制学习机制	视频必须播放完成、文档必须阅读完成才记录为"已完成"

3.2.1 知识列表页

页面元素：

分类筛选（树形）
知识卡片列表：标题、类型图标（文档/视频）、学习状态标签、时长/大小
搜索框（按标题搜索）

学习状态：

状态	说明	显示样式
未学习	从未打开过	灰色标签
学习中	已开始但未完成	蓝色标签 + 进度%
已完成	满足完成条件	绿色标签 ✓

3.2.2 知识详情页

文档类型：

在线预览（PDF直接显示，Word/Excel/PPT转换预览）
学习计时：进入页面开始计时，离开页面停止
完成条件：停留时间 ≥ 预估阅读时间（可配置，默认按页数计算）

视频类型：

在线播放（支持进度条、全屏）
播放进度记录：记录当前播放位置，下次打开从断点继续
完成条件：播放进度 ≥ 90%（可配置）
禁止拖动快进（强制学习模式下）

3.2.3 学习入口场景（🔴 修订项1）

场景一：自由学习（从知识库进入）

入口：左侧菜单"知识库" → 知识列表 → 知识详情
学习完成后：停留在知识详情页，可点击"返回列表"
进度记录：标记来源为 FREE（自由学习）

场景二：培训任务学习（从培训计划进入）

入口：培训详情页 → 点击知识项 → 知识详情
页面顶部显示：返回培训计划入口（如："← 返回《2026年Q1安全规范培训》"）
学习完成后：
- 自动弹出提示："学习完成！是否返回培训计划？"
- 用户可选择【返回培训】或【继续浏览】
进度记录：标记来源为 TRAINING（培训任务），关联 plan_id

进度记录来源区分：

来源	场景	影响
FREE	自由学习	仅记录个人学习进度
TRAINING	培训任务学习	同时更新培训计划进度

说明：无论从哪个入口学习，学习时长和完成状态都会记录。区分来源是为了后续统计分析（如：培训驱动的学习 vs 自主学习）。

3.2.4 学习时长防刷机制（🟡 优化项1）

文档类型防刷策略：

每60秒检测一次用户活跃状态
活跃判定：60秒内有鼠标移动、点击、滚动任一事件
非活跃时：暂停计时，页面显示"检测到您暂时离开，学习计时已暂停"
恢复活跃后：继续计时

视频类型防刷策略：

依赖视频播放事件，暂停时不计时长
无需额外活跃检测

多标签页处理：

同一知识同时只能在一个标签页学习
检测到多标签页打开同一知识时，后打开的标签页提示"该知识已在其他窗口学习中"

验收标准

只显示本部门、已发布状态的知识
分类树正确展示，点击分类筛选对应知识
文档能正常在线预览（至少支持PDF）
视频能正常播放，支持暂停、音量调节
视频播放进度自动保存，刷新页面后从断点继续
强制学习模式下，视频不能快进跳过
学习时长准确记录（精确到秒）
满足完成条件后自动标记为"已完成"
学习进度与培训计划进度联动
🔴 从培训计划进入的知识学习，顶部显示返回入口
🔴 学习完成后弹出返回培训计划提示（仅培训任务学习场景）
🟡 文档学习时，非活跃状态暂停计时
🟡 同一知识不能在多个标签页同时学习

3.3 在线考试

用户故事

作为学员，我希望参加分配给我的考试，并能查看成绩和排名。

功能清单

功能项	说明
考试列表	展示分配给我的所有考试
考试详情	显示考试信息、我的考试记录
在线答题	单选/多选/判断题作答
断点续考	中途退出后可继续答题
自动交卷	时间到自动提交
成绩查看	显示得分、答案解析
成绩排名	显示我在本次考试中的排名

3.3.1 考试列表页

列表字段：

字段	说明
考试名称	点击进入考试详情
考试时间	开始时间 ~ 结束时间
考试状态	未开始/进行中/已结束
我的状态	未参加/考试中/已完成
最高成绩	多次考试取最高分
剩余次数	最大次数 - 已考次数
操作	进入考试/查看成绩

筛选条件：

考试状态：全部/进行中/已结束
我的状态：全部/未完成/已完成

3.3.2 考试详情页（进入考试前）

显示信息：

考试名称、考试时间窗口
考试规则：时长、总分、及格线、最大次数
我的考试记录表格（第N次、得分、是否通过、时间）
【开始考试】/【继续考试】按钮

按钮逻辑：

场景	按钮状态
不在时间窗口内	禁用，提示"考试未开始"或"考试已结束"
次数已用完	禁用，提示"考试次数已用完"
有进行中的考试记录	显示【继续考试】
可以开始新考试	显示【开始考试】

3.3.3 在线答题页

页面布局：

┌─────────────────────────────────────────────────────────┐
│  考试名称                              剩余时间: 45:23  │
├─────────────────────────────────────────────────────────┤
│  第 3 题 / 共 20 题                          [单选题]   │
│  ─────────────────────────────────────────────────────  │
│  题干内容...                                            │
│                                                         │
│  ○ A. 选项A                                            │
│  ● B. 选项B（已选中）                                  │
│  ○ C. 选项C                                            │
│  ○ D. 选项D                                            │
├─────────────────────────────────────────────────────────┤
│  答题卡: [1✓] [2✓] [3●] [4○] [5○] ...                  │
├─────────────────────────────────────────────────────────┤
│            [上一题]              [下一题]      [交卷]   │
└─────────────────────────────────────────────────────────┘

功能说明：

功能	说明
倒计时	显示剩余时间，最后5分钟变红色提醒
题目导航	点击答题卡数字可跳转到对应题目
答案自动保存	选择答案后自动保存到服务器（每30秒或切题时）
上一题/下一题	切换题目
交卷	弹出确认框，确认后提交
自动交卷	时间结束自动提交当前答案

断点续考机制：

考试开始后创建考试记录，状态为"进行中"
答案实时保存到服务器
中途关闭浏览器/断网，考试记录保持"进行中"
重新打开考试，检测到进行中记录，恢复到上次状态
倒计时从剩余时间继续（服务端计算：考试时长 - 已用时间）
超时未提交的考试，由定时任务自动交卷

3.3.5 超时自动交卷机制（🔴 修订项2）

超时判定规则：

超时时间点 = 考试记录开始时间 + 考试时长（分钟）

示例：

学员A在 10:00 开始考试，考试时长60分钟
超时时间点 = 10:00 + 60分钟 = 11:00
无论考试时间窗口是否结束，11:00后该考试记录即视为超时

定时任务策略：

配置项	值	说明
执行频率	每1分钟	Cron: `0 /1 * * ?`
扫描范围	状态为IN_PROGRESS的考试记录	只处理进行中的记录
超时判定	当前时间 > 开始时间 + 考试时长	精确到秒
处理动作	自动提交当前已保存的答案，计算成绩	标记为系统自动交卷

并发提交处理（乐观锁）：

场景：学员在超时前1秒点击交卷，同时定时任务也在处理该记录

处理策略：

考试记录表增加 version 字段（乐观锁）
提交时检查 status = IN_PROGRESS AND version = 当前版本
更新时 version = version + 1
若更新失败（version已变），说明已被其他请求处理，直接返回已提交的结果

状态流转：

IN_PROGRESS  ──用户主动交卷──▶  SUBMITTED（来源：USER）
     │
     └──────定时任务超时交卷──▶  SUBMITTED（来源：SYSTEM_TIMEOUT）

交卷来源标记：

来源	说明
USER	用户主动交卷
SYSTEM_TIMEOUT	系统超时自动交卷

注意：即使考试时间窗口已结束，只要考试记录未超时，学员仍可继续答题（但无法开始新的考试）

3.3.6 考试结果页

显示内容：

项目	说明
得分	大字显示，及格绿色/不及格红色
是否通过	通过✓ / 未通过✗
排名	"您的成绩排名第 X 名（共 Y 人参加）"
答题详情	每道题的正确答案、我的答案、解析
操作按钮	【再考一次】（有次数）/ 【返回列表】

答案解析显示策略（🟡 优化项4）：

交卷后立即显示所有题目的答案解析
无论考试是否通过，都显示解析
目的：培训学习为主，帮助学员理解错误原因

3.3.7 排名计算规则（🔴 修订项3）

计算时机：

实时计算：每次交卷时计算排名
非定时计算：不采用批量定时计算方式

统计范围：

范围：当前考试的所有参与者（被分配且已交卷的学员）
跨部门：若考试分配给多个部门，排名为所有参与者的总排名

排名规则：

优先级	规则	说明
1	最高成绩降序	成绩高的排名靠前
2	达到最高成绩的时间升序	成绩相同时，先达到该成绩的排名靠前

"共Y人参加"统计口径：

统计项	是否计入
已交卷学员	✅ 计入
正在考试中（未交卷）	❌ 不计入
被分配但未参加	❌ 不计入

排名示例：

考试：安全规范考核
分配对象：部门A（30人）、部门B（20人）

参与情况：
- 部门A：25人已交卷，5人未参加
- 部门B：18人已交卷，2人正在考试中

排名统计：共 43 人参加（25 + 18 = 43）

排名结果：
第1名：张三（95分，首次达到时间 10:30）
第2名：李四（95分，首次达到时间 10:45）
第3名：王五（90分）
...

实现建议：

交卷时实时计算排名并返回

排名计算SQL示例思路：

SELECT user_id, MAX(score) as best_score, MIN(submit_time) as first_best_time
FROM ex_exam_record
WHERE exam_id = ? AND status = 'SUBMITTED'
GROUP BY user_id
ORDER BY best_score DESC, first_best_time ASC

验收标准

只显示分配给当前学员的考试
考试状态、我的状态准确显示
不在时间窗口内无法进入考试
次数用完无法再次考试
答题过程中答案实时保存
刷新页面/重新进入可继续答题（断点续考）
倒计时准确，超时自动交卷
交卷后立即显示成绩和排名
答案解析正确显示
多次考试取最高分显示
🔴 定时任务每分钟执行，自动处理超时考试记录
🔴 并发交卷场景下数据一致（乐观锁机制）
🔴 排名实时计算，仅统计已交卷学员
🔴 排名规则：最高分优先，同分按首次达到时间排序

3.4 我的培训

用户故事

作为学员，我希望查看分配给我的培训计划，跟踪学习进度，完成培训任务。

功能清单

功能项	说明
培训列表	展示分配给我的培训计划
培训详情	显示计划内容、学习进度
进度跟踪	实时显示知识学习、考试完成情况
完成判定	根据必修项判定培训是否完成
证书预留	培训完成后预留证书/徽章展示位置

3.4.1 培训列表页

列表字段：

字段	说明
培训名称	点击进入详情
培训周期	开始日期 ~ 结束日期
状态	未开始/进行中/已结束
我的进度	进度条 + 百分比
完成状态	未完成/已完成

3.4.2 培训详情页

页面结构：

┌─────────────────────────────────────────────────────────┐
│  2026年Q1安全规范培训                                   │
│  ─────────────────────────────────────────────────────  │
│  培训周期：2026-01-01 ~ 2026-03-31                     │
│  培训目标：掌握高速公路救援安全规范...                   │
│  我的进度：████████░░░░ 75%                            │
├─────────────────────────────────────────────────────────┤
│  📚 学习内容 (3/5)                                      │
│  ├─ ✅ 高速救援SOP手册          [必修] [已完成]        │
│  ├─ ✅ 安全操作视频             [必修] [已完成]        │
│  ├─ 🔵 应急处理流程            [必修] [学习中 60%]     │
│  ├─ ⚪ 设备使用指南             [选修] [未学习]        │
│  └─ ✅ 案例分析                [选修] [已完成]        │
├─────────────────────────────────────────────────────────┤
│  📝 考试任务 (1/2)                                      │
│  ├─ ✅ 安全规范考核             [必考] [已通过 85分]   │
│  └─ ⚪ 操作技能测试             [必考] [未参加]        │
├─────────────────────────────────────────────────────────┤
│  🏆 完成奖励                                            │
│  └─ 完成培训后可获得【安全规范认证】徽章（敬请期待）    │
└─────────────────────────────────────────────────────────┘

进度计算规则：

培训进度 = (已完成必修知识数 + 已通过必考考试数) / (必修知识总数 + 必考考试总数) × 100%

完成判定规则：

条件	说明
所有必修知识已完成	✓
所有必考考试已通过	✓
选修知识	不影响完成判定
选考考试	不影响完成判定

验收标准

只显示分配给当前学员的培训计划
进度百分比计算准确（只计算必修项）
学习内容、考试任务分开展示
显示每项的必修/选修、必考/选考标签
点击知识内容可跳转到知识详情页
点击考试任务可跳转到考试页面
所有必修项完成后，培训状态变为"已完成"
证书/徽章区域预留（V1显示"敬请期待"）

3.5 个人中心

用户故事

作为学员，我希望查看自己的学习记录、考试历史和获得的证书。

功能清单

功能项	说明
个人信息	显示姓名、部门、角色
学习统计	总学习时长、完成课程数
学习记录	知识学习历史列表
考试记录	考试历史列表
我的证书	证书/徽章展示（预留）

验收标准

正确显示当前用户信息
学习时长统计准确（累计所有知识学习时长）
学习记录按时间倒序展示
考试记录显示每次考试的详情
证书模块预留（V1显示"暂无证书"）

四、数据契约补充

4.1 新增/修改实体

知识学习进度表 (km_knowledge_progress) - 新增

字段	类型	说明
id	Long	主键
user_id	Long	学员ID
knowledge_id	Long	知识ID
department_id	Long	🟡 新增所属部门（冗余字段，便于按部门统计）
status	Enum	状态：NOT_STARTED/IN_PROGRESS/COMPLETED
progress	Integer	进度百分比（0-100）
duration	Long	学习时长（秒）
video_position	Long	视频播放位置（秒），仅视频类型
source	Enum	🔴 新增学习来源：FREE/TRAINING
plan_id	Long	🔴 新增关联培训计划ID（来源为TRAINING时有值）
start_time	DateTime	首次学习时间
complete_time	DateTime	完成时间
update_time	DateTime	最后更新时间

考试记录表 (ex_exam_record) - 补充字段

字段	类型	说明
status	Enum	新增状态：IN_PROGRESS/SUBMITTED
last_save_time	DateTime	新增最后保存时间（断点续考用）
version	Integer	🔴 新增乐观锁版本号
submit_source	Enum	🔴 新增交卷来源：USER/SYSTEM_TIMEOUT

4.2 新增枚举

// 学习状态
public enum LearningStatus {
    NOT_STARTED,  // 未学习
    IN_PROGRESS,  // 学习中
    COMPLETED     // 已完成
}

// 🔴 学习来源
public enum LearningSource {
    FREE,      // 自由学习（从知识库直接进入）
    TRAINING   // 培训任务学习（从培训计划进入）
}

// 考试记录状态
public enum ExamRecordStatus {
    IN_PROGRESS,  // 考试中（用于断点续考）
    SUBMITTED     // 已提交
}

// 🔴 交卷来源
public enum SubmitSource {
    USER,           // 用户主动交卷
    SYSTEM_TIMEOUT  // 系统超时自动交卷
}

五、接口预留（V2/V3功能）

5.1 证书/徽章接口（预留）

POST /api/certificate/generate    # 生成证书
GET  /api/certificate/my          # 我的证书列表
GET  /api/certificate/{id}        # 证书详情
GET  /api/badge/my                # 我的徽章列表

5.2 错题本接口（V2预留）

GET  /api/wrong-questions         # 错题列表
POST /api/wrong-questions/review  # 标记已复习

六、非功能需求

项目	要求	测试指标（🟡 优化项5）
页面加载	页面加载 < 2秒	95%请求 < 2秒
考试提交	考试提交 < 1秒	99%请求 < 1秒
并发支持	支持100人同时在线考试	100并发答题，响应时间 < 500ms，成功率 > 99.9%
答案保存	答案自动保存	保存成功率 > 99.99%，保存延迟 < 300ms
数据安全	考试答案定时自动保存，防止数据丢失	断网重连后数据无丢失
兼容性	支持主流浏览器	Chrome 90+、Edge 90+、Firefox 90+

七、不做什么（Out of Scope）

功能	原因
移动端适配	V1仅支持PC浏览器
防作弊功能	产品确认不需要
学习日历	产品确认不需要
错题本	V2规划
社交功能（评论、点赞）	V3规划

八、页面清单（🟡 优化项3）

说明：采用与管理端复用同一套系统的方案，按角色控制菜单和功能显示，不使用独立的 /student/ 路径前缀。

页面	路径	角色可见	说明
工作台	/index.html	全角色	根据角色显示不同内容
知识列表	/knowledge/list.html	全角色	学员只读，讲师可管理
知识详情	/knowledge/view.html?id={id}	全角色	学员增加学习进度记录
考试列表	/exam/my-exams.html	学员	我的考试列表
考试详情	/exam/detail.html?id={id}	学员	考试信息页
在线答题	/exam/answer.html?id={id}	学员	答题页面
考试结果	/exam/result.html?recordId={id}	学员	成绩结果页
培训列表	/training/my-training.html	学员	我的培训列表
培训详情	/training/detail.html?id={id}	学员	培训计划详情
个人中心	/profile/index.html	全角色	个人信息页
学习记录	/profile/learning.html	学员	学习记录列表
考试记录	/profile/exam-history.html	学员	考试记录列表
我的证书	/profile/certificate.html	学员	证书展示（预留）

菜单权限控制：

菜单项	管理员	讲师	学员
工作台	✅	✅	✅
知识库	✅ 管理	✅ 管理	✅ 只读学习
考题管理	✅	✅	❌
试卷管理	✅	✅	❌
考试管理	✅	✅	❌
我的考试	❌	❌	✅
培训计划	✅	✅	❌
我的培训	❌	❌	✅
个人中心	✅	✅	✅
系统设置	✅	❌	❌

九、修订项对照表

修订项	类型	章节位置	状态
知识学习入口场景	🔴 必须修正	3.2.3	✅ 已补充
断点续考超时机制	🔴 必须修正	3.3.5	✅ 已补充
排名计算规则	🔴 必须修正	3.3.7	✅ 已补充
学习时长防刷机制	🟡 建议优化	3.2.4	✅ 已采纳
数据表department_id	🟡 建议优化	4.1	✅ 已采纳
页面路径设计	🟡 建议优化	8	✅ 已调整
答案解析显示策略	🟡 建议优化	3.3.6	✅ 已明确
非功能需求测试指标	🟡 建议优化	6	✅ 已补充

文档状态：✅ 已批准

Supervisor 复审结论：通过 复审日期：2026-01-15 下一阶段：技术评审 → 开发

26 KiB Raw Permalink Blame History Unescape Escape

学员端功能需求文档

版本更新记录

V1.0.1 (2026-01-15)

一、概述

1.1 目标用户

1.2 核心目标

二、功能模块总览

三、详细功能需求

3.1 工作台（首页）

用户故事

功能清单

验收标准

3.2 知识学习

用户故事

功能清单

3.2.1 知识列表页

3.2.2 知识详情页

3.2.3 学习入口场景（🔴 修订项1）

3.2.4 学习时长防刷机制（🟡 优化项1）

验收标准

3.3 在线考试

用户故事

功能清单

3.3.1 考试列表页

3.3.2 考试详情页（进入考试前）

3.3.3 在线答题页

3.3.5 超时自动交卷机制（🔴 修订项2）

3.3.6 考试结果页

3.3.7 排名计算规则（🔴 修订项3）

验收标准

3.4 我的培训

用户故事

功能清单

3.4.1 培训列表页

3.4.2 培训详情页

验收标准

3.5 个人中心

用户故事

功能清单

验收标准

四、数据契约补充

4.1 新增/修改实体

知识学习进度表 (km_knowledge_progress) - 新增

考试记录表 (ex_exam_record) - 补充字段

4.2 新增枚举

五、接口预留（V2/V3功能）

5.1 证书/徽章接口（预留）

5.2 错题本接口（V2预留）

六、非功能需求

七、不做什么（Out of Scope）

八、页面清单（🟡 优化项3）

九、修订项对照表

26 KiB

Raw Permalink Blame History