server/training-system
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

2026-05-12

Browse Source
This commit is contained in:
尹清林
2026-05-12 12:24:11 +08:00
parent db71245cbd
commit b20da3cd06
597 changed files with 24930 additions and 35355 deletions
Download Patch File Download Diff File Expand all files Collapse all files

881
training/context/01-产品文档/PRD.md Normal file
View File

@@ -0,0 +1,881 @@
# 道路救援企业培训系统 - 产品需求文档 (PRD)
> 版本：V1.0.1
> 更新日期：2026-01-13
> 状态：已确认
---
## 版本更新记录
### V1.0.1 (2026-01-13)
**【培训计划】多考试任务支持**
| 变更项 | 变更前 | 变更后 |
|-------|-------|-------|
| 考试任务数量 | 最多关联1个考试 | 支持关联多个考试 |
| 考试属性 | 无 | 支持设置必考/选考 |
| 考试排序 | 无 | 支持自定义排序 |
**功能说明：**
- 创建/编辑培训计划时，可添加多个考试任务
- 每个考试可设置为"必考"或"选考"
- 学员端展示所有关联考试及通过状态
- 列表页显示考试任务总数
**数据库变更：**
- 新增 `tr_plan_exam` 关联表
- 移除 `tr_plan` 表的 `exam_id` 字段
- ⚠️ 不兼容历史数据，需重新初始化数据库
---
### V1.0.0 (2026-01-08)
- 初始版本发布
- 包含：系统基础、人员管理、知识库、考题管理、试卷管理、考试管理、培训计划六大模块
---
## 一、核心目标 (Mission)
**为道路救援企业打造一站式内部培训平台，通过知识沉淀、在线考核、培训管理三大核心能力，提升500名员工的专业技能水平和服务标准化程度。**
---
## 二、用户画像 (Persona)
| 角色 | 人数估算 | 核心痛点 | 使用场景 |
|------|----------|----------|----------|
| **管理员** | 3-5人 | 人员管理分散，培训效果难追踪 | 配置系统、管理组织架构、分配权限 |
| **讲师（技师）** | 30-50人 | 知识传承依赖口口相传，出题组卷效率低 | 上传知识文档、创建题库、发布考试 |
| **学员** | 450人左右 | 学习资料分散、考试不便、进度不清晰 | 查阅知识库、完成培训任务、参加考试 |
---
## 三、版本规划
### V1：最小可行产品 (MVP)
#### 模块一：系统基础与人员管理
| 功能 | 说明 |
|----------|-----------------------------|
| 企业微信授权登录 | 企业微信授权登录 |
| 组织架构管理 | 中心 → 部门（≤8）→ 小组（≤10/部门）三级结构 |
| 员工管理 | 管理员手动录入员工信息，分配角色（管理员/讲师/学员） |
| 权限控制 | 基于角色的权限隔离，数据按部门隔离 |
#### 模块二：知识库（重点）
| 功能 | 说明 |
|------|------|
| 分类目录 | 支持多级分类（如：安全规范 > 高速救援 > 操作手册）|
| 文档管理 | 支持上传 PDF/Word/Excel/PPT 等常见文档格式 |
| 视频管理 | 支持上传视频文件，在线播放 |
| 在线预览 | 文档、视频无需下载即可在线查看 |
| 状态管理 | 草稿 → 已发布 → 已下架 |
| 部门隔离 | 各部门只能查看本部门的知识内容 |
#### 模块三：考题管理
| 功能 | 说明 |
|------|------|
| 题型支持 | 单选题、多选题、判断题 |
| 题目解析 | 每道题必须填写答案解析 |
| 题库分类 | 按分类/章节管理题目 |
| 状态管理 | 草稿 → 已发布 → 已下架 |
| 部门隔离 | 讲师只能管理本部门题库 |
#### 模块四：试卷管理
| 功能 | 说明 |
|------|------|
| 手动组卷 | 讲师手动从题库选题组成试卷 |
| 自动组卷 | 设置规则（单选X题+多选Y题+判断Z题），系统随机抽题 |
| 试卷配置 | 设置总分、题目分值、考试时长 |
| 试卷预览 | 组卷完成后可预览试卷效果 |
| 状态管理 | 草稿 → 已发布 → 已下架 |
#### 模块五：考试管理
| 功能 | 说明 |
|------|------|
| 发布考试 | 选择试卷，设置考试名称、时间窗口（开始~结束时间）|
| 指定对象 | 支持指定部门 / 小组 / 个人参加考试 |
| 考试规则 | 设置及格线、限制考试次数、考试时长 |
| 在线答题 | 学员在线作答，自动计时，超时自动交卷 |
| 成绩查看 | 交卷后立即显示成绩和答案解析 |
#### 模块六：培训计划
| 功能 | 说明 |
|------|------|
| 创建培训计划 | 设置计划名称、培训周期、培训目标 |
| 关联知识/考试 | 一个培训计划可包含多个知识文档 + 多场考试（V1.0.1+） |
| 考试属性设置 | 每个考试可设置必考/选考、自定义排序（V1.0.1+） |
| 分配学员 | 指定部门/小组/个人参加培训计划 |
| 进度跟踪 | 学员可查看自己的学习进度和考试状态 |
| 计划状态 | 未开始 / 进行中 / 已结束 |
### V2 及以后版本 (Future Releases)
| 版本 | 功能 | 价值 |
|------|------|------|
| **V2** | 统计报表中心 | 培训完成率、考试通过率、部门排名等数据看板 |
| **V2** | 线下培训签到 | 扫码签到/签退，记录实际培训时长 |
| **V2** | 错题本 | 学员自动收集错题，巩固薄弱知识点 |
| **V3** | 知识库增强 | 收藏、点赞、评论、全文搜索 |
| **V3** | 奖励体系 | 积分、勋章、学习排行榜 |
| **V3** | 证书管理 | 培训/考试
---
## 四、关键业务逻辑 (Business Rules)
### 4.1 权限规则
```
管理员：
├── 管理所有中心、部门、小组
├── 管理所有用户（增删改查、角色分配）
├── 查看全平台数据
└── 系统配置
讲师：
├── 管理本部门知识库（上传/编辑/删除）
├── 管理本部门题库（增删改查）
├── 创建/管理本部门试卷和考试
├── 创建/管理本部门培训计划
└── 查看本部门学员成绩
学员：
├── 查看本部门知识库（只读）
├── 参加分配给自己的培训计划
├── 参加分配给自己的考试
└── 查看个人学习记录和成绩
```
### 4.2 内容状态流转
```
┌─────────┐ 发布 ┌─────────┐ 下架 ┌─────────┐
│ 草稿 │ ───────────▶ │ 已发布 │ ───────────▶ │ 已下架 │
│ DRAFT │ │PUBLISHED │ │ OFFLINE │
└─────────┘ └─────────┘ └─────────┘
▲ │ │
│ │ 重新上架 │
│ ◀────────────────────────┘
│
└──────── 可继续编辑 ─────────────────────────────┘
```
| 状态 | 说明 | 学员可见 |
|------|------|----------|
| **草稿 (DRAFT)** | 讲师编辑中，未完成 | ❌ 不可见 |
| **已发布 (PUBLISHED)** | 正式生效，可被使用 | ✅ 可见 |
| **已下架 (OFFLINE)** | 临时隐藏，保留数据 | ❌ 不可见 |
### 4.3 考试规则
| 规则 | 说明 |
|------|------|
| 时间窗口 | 只有在考试开放时间内才能进入考试 |
| 限时作答 | 超过考试时长自动交卷 |
| 限制次数 | 达到最大次数后不可再考，取最高分 |
| 及格判定 | 分数 ≥ 及格线 为通过 |
| 答题顺序 | 自动组卷时题目顺序随机打乱 |
### 4.4 数据隔离规则
| 数据类型 | 隔离方式 |
|----------|----------|
| 知识库 | 按部门隔离，只能看本部门 |
| 题库 | 按部门隔离，讲师只能操作本部门 |
| 试卷/考试 | 按部门隔离 |
| 培训计划 | 按部门隔离 |
| 员工信息 | 管理员可见全部，讲师可见本部门 |
### 4.5 引用保护规则
| 场景 | 规则 |
|------|------|
| 题目下架 | 已被试卷引用的题目，下架前需确认警告 |
| 试卷下架 | 已被考试引用的试卷，下架前需确认警告 |
| 知识下架 | 已被培训计划引用的知识，下架前需确认警告 |
---
## 五、数据契约 (Data Contract)
### 5.1 核心实体
#### 用户 (sys_user)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| wx_userid | String | 企业微信用户ID |
| real_name | String | 姓名 |
| phone | String | 手机号 |
| role | Enum | 角色：ADMIN/LECTURER/STUDENT |
| department_id | Long | 所属部门 |
| group_id | Long | 所属小组（可空） |
| status | Enum | 状态：ENABLED/DISABLED |
| create_time | DateTime | 创建时间 |
#### 组织架构 (sys_center / sys_department / sys_group)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| name | String | 名称 |
| parent_id | Long | 上级ID（部门关联中心，小组关联部门） |
| sort_order | Integer | 排序 |
| create_time | DateTime | 创建时间 |
#### 知识分类 (km_category)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| name | String | 分类名称 |
| parent_id | Long | 父分类ID |
| department_id | Long | 所属部门 |
| sort_order | Integer | 排序 |
#### 知识 (km_knowledge)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| title | String | 标题 |
| category_id | Long | 所属分类 |
| type | Enum | 类型：DOCUMENT/VIDEO |
| file_url | String | 文件地址 |
| file_size | Long | 文件大小 |
| department_id | Long | 所属部门 |
| status | Enum | 状态：DRAFT/PUBLISHED/OFFLINE |
| creator_id | Long | 创建人 |
| create_time | DateTime | 创建时间 |
| publish_time | DateTime | 发布时间 |
#### 题目 (ex_question)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| type | Enum | 题型：SINGLE/MULTIPLE/JUDGE |
| content | String | 题干 |
| options | JSON | 选项列表（判断题为空） |
| answer | String | 正确答案 |
| analysis | String | 解析 |
| category_id | Long | 所属分类 |
| department_id | Long | 所属部门 |
| status | Enum | 状态：DRAFT/PUBLISHED/OFFLINE |
| creator_id | Long | 创建人 |
| create_time | DateTime | 创建时间 |
| publish_time | DateTime | 发布时间 |
#### 试卷 (ex_paper)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| title | String | 试卷名称 |
| total_score | Integer | 总分 |
| duration | Integer | 考试时长（分钟） |
| pass_score | Integer | 及格分 |
| department_id | Long | 所属部门 |
| status | Enum | 状态：DRAFT/PUBLISHED/OFFLINE |
| creator_id | Long | 创建人 |
| create_time | DateTime | 创建时间 |
| publish_time | DateTime | 发布时间 |
#### 试卷题目关联 (ex_paper_question)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| paper_id | Long | 试卷ID |
| question_id | Long | 题目ID |
| score | Integer | 该题分值 |
| sort_order | Integer | 排序 |
#### 考试 (ex_exam)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| title | String | 考试名称 |
| paper_id | Long | 关联试卷 |
| start_time | DateTime | 开始时间 |
| end_time | DateTime | 结束时间 |
| max_attempts | Integer | 最大考试次数 |
| department_id | Long | 所属部门 |
| status | Enum | 状态：NOT_STARTED/IN_PROGRESS/ENDED |
| creator_id | Long | 创建人 |
| create_time | DateTime | 创建时间 |
#### 考试对象 (ex_exam_target)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| exam_id | Long | 考试ID |
| target_type | Enum | 对象类型：DEPARTMENT/GROUP/USER |
| target_id | Long | 对象ID |
#### 考试记录 (ex_exam_record)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| exam_id | Long | 考试ID |
| user_id | Long | 学员ID |
| attempt_no | Integer | 第几次考试 |
| score | Integer | 得分 |
| passed | Boolean | 是否通过 |
| start_time | DateTime | 开始时间 |
| submit_time | DateTime | 提交时间 |
| answers | JSON | 答题详情 |
#### 培训计划 (tr_plan)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| title | String | 计划名称 |
| description | String | 计划描述 |
| start_date | Date | 开始日期 |
| end_date | Date | 结束日期 |
| department_id | Long | 所属部门 |
| exam_id | Long | 关联考试（可空） |
| status | Enum | 状态：NOT_STARTED/IN_PROGRESS/ENDED |
| creator_id | Long | 创建人 |
| create_time | DateTime | 创建时间 |
#### 培训计划-知识关联 (tr_plan_knowledge)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| plan_id | Long | 计划ID |
| knowledge_id | Long | 知识ID |
| required | Boolean | 是否必修 |
| sort_order | Integer | 排序 |
#### 培训计划-对象 (tr_plan_target)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| plan_id | Long | 计划ID |
| target_type | Enum | 对象类型：DEPARTMENT/GROUP/USER |
| target_id | Long | 对象ID |
#### 培训进度 (tr_plan_progress)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| plan_id | Long | 计划ID |
| user_id | Long | 学员ID |
| knowledge_id | Long | 知识ID |
| completed | Boolean | 是否完成 |
| complete_time | DateTime | 完成时间 |
---
## 六、原型设计（方案A - 经典管理后台风格）
### 6.1 设计理念
左侧固定导航 + 右侧内容区，层级分明，适合功能复杂的企业管理系统。学习成本低，用户容易上手。
### 6.2 布局结构
```
┌────────────────────────────────────────────────────────────────────────────┐
│ 🚗 道路救援培训系统 🔔 消息 👤 张三 ▼ │
├──────────────────┬─────────────────────────────────────────────────────────┤
│ │ │
│ 📊 工作台 │ 内容区域 │
│ │ │
│ 👥 人员管理 ▶ │ │
│ ├ 组织架构 │ │
│ ├ 员工管理 │ │
│ └ 讲师管理 │ │
│ │ │
│ 📚 知识库 ▶ │ │
│ ├ 知识分类 │ │
│ └ 知识列表 │ │
│ │ │
│ ✏️ 考题管理 ▶ │ │
│ ├ 题库分类 │ │
│ └ 题目列表 │ │
│ │ │
│ 📄 试卷管理 │ │
│ │ │
│ 📝 考试管理 │ │
│ │ │
│ 📅 培训计划 │ │
│ │ │
│ ────────────── │ │
│ ⚙️ 系统设置 │ │
│ │ │
└──────────────────┴─────────────────────────────────────────────────────────┘
```
### 6.3 核心页面原型
#### 工作台首页
```
┌────────────────────────────────────────────────────────────────────────────┐
│ 🚗 道路救援培训系统 🔔 消息 👤 张三 ▼ │
├──────────────────┬─────────────────────────────────────────────────────────┤
│ │ │
│ 📊 工作台 ● │ 欢迎回来，张三 2026年1月8日 │
│ │ │
│ 👥 人员管理 ▶ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ │ 待学习课程 │ │ 待完成考试 │ │ 培训进度 │ │
│ 📚 知识库 ▶ │ │ │ │ │ │ │ │
│ │ │ 12 │ │ 3 │ │ 75% │ │
│ ✏️ 考题管理 ▶ │ │ │ │ │ │ ████░░ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │
│ 📄 试卷管理 │ │
│ │ ┌──────────────────────────────────────────────────┐ │
│ 📝 考试管理 │ │ 我的培训计划 │ │
│ │ ├──────────────────────────────────────────────────┤ │
│ 📅 培训计划 │ │ 📋 2026年Q1安全规范培训 进行中 60% │ │
│ │ │ 📋 新员工入职培训 进行中 30% │ │
│ │ │ 📋 高速救援操作规范 未开始 -- │ │
│ │ └──────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌──────────────────────────────────────────────────┐ │
│ │ │ 待完成考试 │ │
│ │ ├──────────────────────────────────────────────────┤ │
│ │ │ 📝 安全规范考核 截止: 1月15日 [进入考试] │ │
│ │ │ 📝 月度技能测试 截止: 1月20日 [进入考试] │ │
│ │ └──────────────────────────────────────────────────┘ │
│ │ │
└──────────────────┴─────────────────────────────────────────────────────────┘
```
#### 知识库列表页
```
┌────────────────────────────────────────────────────────────────────────────┐
│ 🚗 道路救援培训系统 🔔 消息 👤 张三 ▼ │
├──────────────────┬─────────────────────────────────────────────────────────┤
│ │ │
│ 📊 工作台 │ 知识库 > 安全规范 │
│ │ ───────────────────────────────────────────────── │
│ 👥 人员管理 ▶ │ │
│ │ [+ 新增知识] [所有状态 ▼] [🔍 搜索知识...] │
│ 📚 知识库 ▼ │ │
│ ┌ 知识分类 │ ┌────────────────────────────────────────────────┐ │
│ └ 知识列表 ● │ │ 标题 类型 状态 更新时间 操作│ │
│ │ ├────────────────────────────────────────────────┤ │
│ ✏️ 考题管理 ▶ │ │ 高速救援SOP 📄文档 已发布 01-05 编辑│ │
│ │ │ 安全操作视频 🎬视频 已发布 01-03 编辑│ │
│ 📄 试卷管理 │ │ 应急处理流程 📄文档 草稿 01-02 编辑│ │
│ │ │ 设备使用手册 📄文档 已下架 12-28 编辑│ │
│ 📝 考试管理 │ └────────────────────────────────────────────────┘ │
│ │ │
│ 📅 培训计划 │ 共 24 条记录 < 1 2 3 4 5 > │
│ │ │
└──────────────────┴─────────────────────────────────────────────────────────┘
```
#### 在线考试页
```
┌────────────────────────────────────────────────────────────────────────────┐
│ 📝 2026年Q1安全规范考试 剩余时间: 45:23 │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 第 3 题 / 共 20 题 [单选题] │ │
│ ├─────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ 高速公路救援作业时，警示标志应放置在故障车辆后方多少米处？ │ │
│ │ │ │
│ │ ○ A. 50米 │ │
│ │ ● B. 150米 │ │
│ │ ○ C. 200米 │ │
│ │ ○ D. 100米 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ 答题卡: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ ✓1 ✓2 ●3 ○4 ○5 ○6 ○7 ○8 ○9 ○10 │ │
│ │ ○11 ○12 ○13 ○14 ○15 ○16 ○17 ○18 ○19 ○20 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ [< 上一题] [下一题 >] [交卷] │
│ │
└────────────────────────────────────────────────────────────────────────────┘
```
#### 试卷组卷页
```
┌────────────────────────────────────────────────────────────────────────────┐
│ 🚗 道路救援培训系统 🔔 消息 👤 张三 ▼ │
├──────────────────┬─────────────────────────────────────────────────────────┤
│ │ │
│ 📊 工作台 │ 创建试卷 > 第2步：选择题目 │
│ │ ═══════════════════════════════════════════════════ │
│ 👥 人员管理 ▶ │ ① 基本信息 ────── ② 选择题目 ────── ③ 预览确认 │
│ │ ● │
│ 📚 知识库 ▶ │ │
│ │ ┌─────────────────────┐ ┌────────────────────────┐ │
│ ✏️ 考题管理 ▶ │ │ 📂 题库 │ │ 📋 已选题目 (15) │ │
│ │ │ ┌─────────────────┐ │ │ │ │
│ 📄 试卷管理 ● │ │ │ [全选] 安全(48) │ │ │ 单选题 x10 30分 │ │
│ │ │ │ ☑ 高速警示... │ │ │ 多选题 x3 15分 │ │
│ 📝 考试管理 │ │ │ ☑ 夜间灯光... │ │ │ 判断题 x2 5分 │ │
│ │ │ │ ☐ 拖车规范... │ │ │ ─────────────── │ │
│ 📅 培训计划 │ │ └─────────────────┘ │ │ 总分: 50分 │ │
│ │ │ │ │ │ │
│ │ │ ── 或自动组卷 ── │ │ [自动组卷] │ │
│ │ │ 单选: [10] 题 │ │ 单选: [10] 题 │ │
│ │ │ 多选: [ 5] 题 │ │ 多选: [ 5] 题 │ │
│ │ │ 判断: [ 5] 题 │ │ 判断: [ 5] 题 │ │
│ │ │ [随机抽题] │ │ [确认随机抽取] │ │
│ │ └─────────────────────┘ └────────────────────────┘ │
│ │ │
│ │ [上一步] [下一步:预览] │
└──────────────────┴─────────────────────────────────────────────────────────┘
```
---
## 七、架构设计蓝图
### 7.1 系统架构总览
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ PC浏览器 │ │ 企业微信H5 │ │ 移动端浏览器 │ │
│ │ (管理员/讲师) │ │ (学员) │ │ (学员) │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
└───────────┼─────────────────────┼─────────────────────┼─────────────────┘
│ │ │
└─────────────────────┼─────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 网关层 │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Spring Boot 应用 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ JWT认证 │ │ 权限拦截 │ │ 日志记录 │ │ 异常处理 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务层 │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ 认证模块 │ │ 组织模块 │ │ 知识库模块│ │ 考试模块 │ │ 培训模块 │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ ·企微登录 │ │ ·组织架构 │ │ ·分类管理 │ │ ·题库管理 │ │ ·计划管理 │ │
│ │ ·Token管理│ │ ·员工管理 │ │ ·知识CRUD │ │ ·试卷管理 │ │ ·任务分配 │ │
│ │ ·权限校验 │ │ ·角色管理 │ │ ·文件上传 │ │ ·考试管理 │ │ ·进度跟踪 │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 数据层 │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ MySQL 8.0 │ │ 文件存储服务 │ │
│ │ (MyBatis Plus ORM) │ │ (本地/OSS/MinIO) │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 7.2 核心流程图
#### 用户登录流程（企业微信OAuth）
```mermaid
sequenceDiagram
participant U as 用户
participant FE as 前端页面
participant BE as 后端服务
participant WX as 企业微信API
participant DB as 数据库
U->>FE: 点击"企业微信登录"
FE->>WX: 跳转企微授权页面
WX->>U: 显示授权确认
U->>WX: 确认授权
WX->>FE: 回调返回code
FE->>BE: 携带code请求登录
BE->>WX: 用code换取access_token
WX-->>BE: 返回access_token
BE->>WX: 获取用户信息(userid)
WX-->>BE: 返回用户信息
BE->>DB: 查询用户是否存在
alt 用户存在
DB-->>BE: 返回用户信息
BE->>BE: 生成JWT Token
BE-->>FE: 返回Token+用户信息
FE->>FE: 存储Token，跳转工作台
else 用户不存在
BE-->>FE: 返回错误:用户未录入
FE->>U: 提示联系管理员
end
```
#### 在线考试流程
```mermaid
sequenceDiagram
participant S as 学员
participant FE as 前端页面
participant BE as 后端服务
participant DB as 数据库
S->>FE: 进入考试列表
FE->>BE: 获取我的考试列表
BE->>DB: 查询分配给该学员的考试
DB-->>BE: 返回考试列表
BE-->>FE: 返回考试列表(含剩余次数)
S->>FE: 点击"开始考试"
FE->>BE: 请求开始考试
BE->>DB: 校验考试状态/次数/时间窗口
alt 校验通过
BE->>DB: 创建考试记录(开始时间)
BE->>DB: 获取试卷题目
DB-->>BE: 返回题目列表
BE-->>FE: 返回试卷内容+考试时长
FE->>FE: 启动倒计时
loop 答题过程
S->>FE: 选择/修改答案
FE->>FE: 本地暂存答案
FE->>BE: 定时自动保存(每30秒)
BE->>DB: 更新答题记录
end
alt 主动交卷
S->>FE: 点击"交卷"
else 时间到
FE->>FE: 倒计时结束
end
FE->>BE: 提交试卷
BE->>BE: 自动判分(客观题)
BE->>DB: 保存成绩+答案详情
BE-->>FE: 返回考试成绩
FE->>S: 显示成绩+答案解析
else 校验失败
BE-->>FE: 返回错误(次数用尽/不在时间窗口)
FE->>S: 提示无法参加考试
end
```
#### 培训计划执行流程
```mermaid
flowchart TB
subgraph 讲师操作
A[创建培训计划] --> B[设置基本信息]
B --> C[关联知识内容]
C --> D[关联考试-可选]
D --> E[指定培训对象]
E --> F[发布培训计划]
end
subgraph 学员学习
F --> G[学员收到培训通知]
G --> H[进入培训计划]
H --> I[学习知识内容]
I --> J{知识学完?}
J -->|否| I
J -->|是| K{有关联考试?}
K -->|否| L[培训完成]
K -->|是| M[参加考试]
M --> N{考试通过?}
N -->|是| L
N -->|否| O{还有考试次数?}
O -->|是| M
O -->|否| P[培训未通过]
end
subgraph 进度追踪
I --> Q[更新学习进度]
M --> R[记录考试成绩]
L --> S[标记培训完成]
end
```
### 7.3 技术选型
| 层次 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **构建** | Maven | 3.8+ | 依赖管理 |
| **框架** | Spring Boot | 3.1.2 | 主框架 |
| **ORM** | MyBatis Plus | 3.5.3+ | 简化CRUD |
| **数据库** | MySQL | 8.0 | 主数据库 |
| **认证** | java-jwt | 4.4+ | JWT Token生成验证 |
| **加密** | Spring Security | 6.x | BCrypt密码加密 |
| **文档** | Springdoc OpenAPI | 2.2+ | API文档 |
| **工具** | Lombok | 1.18+ | 简化代码 |
| **JSON** | Jackson | 内置 | JSON序列化 |
| **文件** | 本地存储 / MinIO | - | V1先用本地，V2可扩展 |
| **前端** | HTML + CSS + JS | - | 原生技术栈 |
#### 关键依赖库
| 用途 | 库 | 说明 |
|------|-----|------|
| 企业微信SDK | weixin-java-cp | 企业微信Java SDK |
| 文件预览 | kkFileView / OnlyOffice | 文档在线预览（可选外部服务） |
| 视频播放 | video.js | 前端视频播放器 |
| Excel导入导出 | EasyExcel | 阿里开源，性能好 |
| 工具库 | Hutool | 常用工具集合 |
### 7.4 风险评估
| 风险点 | 等级 | 描述 | 应对策略 |
|--------|------|------|----------|
| **企业微信对接** | 🟡 中 | 需要企业微信管理员配置应用 | 提前准备配置文档，预留账号密码登录作为备选 |
| **文件预览** | 🟡 中 | 不同格式文档预览兼容性 | V1优先支持PDF+图片+视频，复杂格式提示下载 |
| **大文件上传** | 🟡 中 | 视频文件可能较大 | 限制单文件大小，支持分片上传 |
| **考试并发** | 🟢 低 | 500人规模并发压力不大 | 合理设计索引，必要时加缓存 |
| **数据隔离** | 🟢 低 | 部门数据隔离逻辑 | 统一在Service层实现隔离过滤 |
### 7.5 项目结构
```
training-system/
├── pom.xml
├── src/
│ └── main/
│ ├── java/com/sino/training/
│ │ ├── TrainingApplication.java # 启动类
│ │ │
│ │ ├── common/ # 通用模块
│ │ │ ├── config/ # 配置类
│ │ │ ├── exception/ # 异常处理
│ │ │ ├── result/ # 统一响应
│ │ │ ├── interceptor/ # 拦截器
│ │ │ └── utils/ # 工具类
│ │ │
│ │ ├── module/ # 业务模块
│ │ │ ├── auth/ # 认证模块
│ │ │ ├── system/ # 系统管理
│ │ │ ├── knowledge/ # 知识库模块
│ │ │ ├── exam/ # 考试模块
│ │ │ └── training/ # 培训模块
│ │ │
│ │ └── integration/ # 外部集成
│ │ └── wechat/ # 企业微信
│ │
│ └── resources/
│ ├── application.yml # 主配置
│ ├── application-dev.yml # 开发环境
│ ├── application-prod.yml # 生产环境
│ ├── mapper/ # MyBatis XML
│ ├── static/ # 静态资源
│ └── templates/ # 页面模板
│
├── docs/
│ └── PRD.md # 产品需求文档
│
└── sql/
└── init.sql # 数据库初始化脚本
```
---
## 八、附录
### 8.1 角色菜单权限对照表
| 菜单 | 管理员 | 讲师 | 学员 |
|------|--------|------|------|
| 工作台 | ✅ | ✅ | ✅ |
| 组织架构管理 | ✅ | ❌ | ❌ |
| 员工管理 | ✅ | 👁️ 本部门只读 | ❌ |
| 讲师管理 | ✅ | ❌ | ❌ |
| 知识库-分类管理 | ✅ | ✅ 本部门 | ❌ |
| 知识库-知识列表 | ✅ | ✅ 本部门 | 👁️ 本部门已发布 |
| 考题管理-题库分类 | ✅ | ✅ 本部门 | ❌ |
| 考题管理-题目列表 | ✅ | ✅ 本部门 | ❌ |
| 试卷管理 | ✅ | ✅ 本部门 | ❌ |
| 考试管理 | ✅ | ✅ 本部门 | 👁️ 我的考试 |
| 培训计划 | ✅ | ✅ 本部门 | 👁️ 我的培训 |
| 系统设置 | ✅ | ❌ | ❌ |
### 8.2 状态枚举定义
```java
// 内容状态
public enum ContentStatus {
DRAFT, // 草稿
PUBLISHED, // 已发布
OFFLINE // 已下架
}
// 用户角色
public enum UserRole {
ADMIN, // 管理员
LECTURER, // 讲师
STUDENT // 学员
}
// 用户状态
public enum UserStatus {
ENABLED, // 启用
DISABLED // 禁用
}
// 题目类型
public enum QuestionType {
SINGLE, // 单选题
MULTIPLE, // 多选题
JUDGE // 判断题
}
// 知识类型
public enum KnowledgeType {
DOCUMENT, // 文档
VIDEO // 视频
}
// 考试/培训目标类型
public enum TargetType {
DEPARTMENT, // 部门
GROUP, // 小组
USER // 个人
}
// 考试状态
public enum ExamStatus {
NOT_STARTED, // 未开始
IN_PROGRESS, // 进行中
ENDED // 已结束
}
// 培训计划状态
public enum PlanStatus {
NOT_STARTED, // 未开始
IN_PROGRESS, // 进行中
ENDED // 已结束
}
```
---
**文档状态：已确认，等待开发启动**

664
training/context/01-产品文档/student.md Normal file
View File

@@ -0,0 +1,664 @@
# 学员端功能需求文档
> 版本：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秒点击交卷，同时定时任务也在处理该记录
```
**处理策略**：
1. 考试记录表增加 `version` 字段（乐观锁）
2. 提交时检查 `status = IN_PROGRESS AND version = 当前版本`
3. 更新时 `version = version + 1`
4. 若更新失败（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示例思路：
```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 新增枚举
```java
// 学习状态
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
> **下一阶段**：技术评审 → 开发