2026-05-12
This commit is contained in:
881
training/context/01-产品文档/PRD.md
Normal file
881
training/context/01-产品文档/PRD.md
Normal 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
664
training/context/01-产品文档/student.md
Normal 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
|
||||
> **下一阶段**：技术评审 → 开发
|
||||
379
training/context/02-产品架构/01-产品整体架构.md
Normal file
379
training/context/02-产品架构/01-产品整体架构.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# 产品整体架构文档 — 道路救援企业培训系统
|
||||
|
||||
> 版本：V1.0
|
||||
> 生成日期：2026-04-07
|
||||
> 证据状态：✅ 已验证
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-SQL-01] [SRC-API-01] [SRC-CODE-01]
|
||||
|
||||
---
|
||||
|
||||
## 1. 产品定位
|
||||
|
||||
### 1.1 产品目标
|
||||
|
||||
为道路救援企业提供**一站式内部培训管理平台**，通过数字化方式替代口口相传的知识传承模式，实现知识沉淀、在线考核、培训过程管控三位一体。[SRC-FEAT-01]
|
||||
|
||||
### 1.2 核心价值
|
||||
|
||||
| 价值维度 | 解决的痛点 | 实现方式 |
|
||||
|---------|---------|---------|
|
||||
| 知识沉淀 | 知识依赖口口相传，无法沉淀 | 结构化知识库（文档+视频） |
|
||||
| 高效考核 | 出题组卷效率低，纸质考试成本高 | 在线题库 + 自动/手动组卷 + 在线考试 |
|
||||
| 培训管控 | 培训效果难追踪，进度不透明 | 培训计划+进度跟踪+成绩统计 |
|
||||
| 标准化输出 | 服务标准参差不齐 | 统一平台 + 及格线控制 + 必考机制 |
|
||||
|
||||
### 1.3 目标用户
|
||||
|
||||
| 角色 | 人数 | 核心诉求 |
|
||||
|------|------|---------|
|
||||
| 管理员 | 3-5人 | 系统配置、人员管理、全平台数据可见 |
|
||||
| 讲师（技师） | 30-50人 | 本部门知识上传、出题、发布考试、管理培训计划 |
|
||||
| 学员 | ~450人 | 学习资料、参加考试、查看进度 |
|
||||
|
||||
[SRC-FEAT-01：二、用户画像]
|
||||
|
||||
### 1.4 使用场景
|
||||
|
||||
- **管理员场景**：系统初始化时维护组织架构；日常监控各部门培训完成情况。
|
||||
- **讲师场景**：救援规范更新后，上传新手册并更新题库，发布新考试，关联到培训计划。
|
||||
- **学员场景**：PC端浏览知识库预习、参加指定考试、查看自己的培训进度。
|
||||
- **企业微信场景**：学员通过企业微信 H5 入口完成移动端学习和考试。
|
||||
|
||||
---
|
||||
|
||||
## 2. 系统整体架构
|
||||
|
||||
### 2.1 架构分层
|
||||
|
||||
| 层次 | 组件 | 职责 |
|
||||
|-----|------|------|
|
||||
| **表现层** | PC浏览器（管理员/讲师）、企业微信H5（学员）、移动端浏览器 | 用户交互，HTML+CSS+JS 原生技术栈 |
|
||||
| **网关层** | Spring Boot 应用（JWT认证、权限拦截、日志、异常处理） | 请求入口，统一认证鉴权，全局异常处理 |
|
||||
| **业务层** | 5个业务模块（auth / system / knowledge / exam / training） | 核心业务逻辑，按模块边界划分，禁止跨模块直接调用数据层 |
|
||||
| **数据层** | MySQL 8.0（MyBatis Plus ORM）+ 文件存储（本地/MinIO/OSS） | 持久化业务数据和媒体文件 |
|
||||
|
||||
[SRC-FEAT-01：七、架构设计蓝图]
|
||||
|
||||
### 2.2 技术架构概览
|
||||
|
||||
| 技术选型 | 版本 | 用途 |
|
||||
|---------|------|------|
|
||||
| Spring Boot | 3.1.2 | 主框架 |
|
||||
| MyBatis Plus | 3.5.3+ | ORM，简化CRUD |
|
||||
| MySQL | 8.0 | 主数据库 |
|
||||
| java-jwt | 4.4+ | JWT Token 签发与验证 |
|
||||
| Spring Security | 6.x | BCrypt 密码加密 |
|
||||
| weixin-java-cp | - | 企业微信 SDK（OAuth 登录） |
|
||||
| Springdoc OpenAPI | 2.2+ | API 文档 |
|
||||
| Spring @Scheduled | - | 考试超时自动交卷定时任务 |
|
||||
| 文件存储 | - | V1 本地存储，V2 可扩展 MinIO/OSS |
|
||||
|
||||
[SRC-FEAT-01：7.3 技术选型]
|
||||
|
||||
### 2.3 系统依赖关系
|
||||
|
||||
```
|
||||
外部系统依赖：
|
||||
企业微信API ←→ auth 模块（OAuth 换 userid）
|
||||
文件存储服务 ←→ knowledge 模块（上传/下载文件）
|
||||
文档预览服务（可选） ←→ knowledge 模块（在线预览）
|
||||
|
||||
内部模块依赖方向（单向，禁止逆向调用）：
|
||||
training → knowledge（引用知识内容、学习进度）
|
||||
training → exam（引用考试通过状态）
|
||||
knowledge / exam / training → system（查询用户/部门信息）
|
||||
所有模块 → auth（权限校验拦截器）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 业务架构图
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph 客户端
|
||||
PC[PC浏览器<br>管理员/讲师]
|
||||
WX[企业微信H5<br>学员]
|
||||
MB[移动端浏览器<br>学员]
|
||||
end
|
||||
|
||||
subgraph 后端服务
|
||||
subgraph 网关层
|
||||
GW[JWT认证 / 权限拦截 / 异常处理]
|
||||
end
|
||||
|
||||
subgraph 业务域
|
||||
AUTH[认证模块<br>auth]
|
||||
SYS[系统管理<br>system]
|
||||
KM[知识库模块<br>knowledge]
|
||||
EX[考试模块<br>exam]
|
||||
TR[培训模块<br>training]
|
||||
end
|
||||
end
|
||||
|
||||
subgraph 数据层
|
||||
DB[(MySQL 8.0)]
|
||||
FS[文件存储<br>本地/MinIO]
|
||||
end
|
||||
|
||||
subgraph 外部服务
|
||||
WXAPI[企业微信API]
|
||||
PREVIEW[文档预览服务<br>可选]
|
||||
end
|
||||
|
||||
PC --> GW
|
||||
WX --> GW
|
||||
MB --> GW
|
||||
GW --> AUTH
|
||||
GW --> SYS
|
||||
GW --> KM
|
||||
GW --> EX
|
||||
GW --> TR
|
||||
|
||||
AUTH --> WXAPI
|
||||
KM --> FS
|
||||
KM --> PREVIEW
|
||||
|
||||
TR --> KM
|
||||
TR --> EX
|
||||
KM --> SYS
|
||||
EX --> SYS
|
||||
TR --> SYS
|
||||
|
||||
AUTH --> DB
|
||||
SYS --> DB
|
||||
KM --> DB
|
||||
EX --> DB
|
||||
TR --> DB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心业务流程说明
|
||||
|
||||
### 4.1 用户主流程（学员）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 学员
|
||||
participant 前端
|
||||
participant 后端
|
||||
participant 企业微信
|
||||
|
||||
学员->>前端: 点击企业微信登录
|
||||
前端->>企业微信: 跳转 OAuth 授权
|
||||
企业微信-->>前端: 返回 code
|
||||
前端->>后端: code 换 Token
|
||||
后端->>企业微信: code → userid
|
||||
后端->>后端: 查 sys_user 匹配
|
||||
alt 用户已录入
|
||||
后端-->>前端: JWT Token + 用户信息
|
||||
前端->>学员: 进入工作台
|
||||
else 用户未录入
|
||||
后端-->>前端: 错误：联系管理员
|
||||
end
|
||||
|
||||
学员->>前端: 查看培训计划
|
||||
前端->>后端: GET /api/student/training
|
||||
后端-->>前端: 计划列表 + 进度
|
||||
|
||||
学员->>前端: 参加考试
|
||||
前端->>后端: POST /api/student/exam/{id}/start
|
||||
后端->>后端: 校验时间窗口 + 剩余次数
|
||||
后端-->>前端: 试题 + 考试时长
|
||||
学员->>前端: 答题 + 交卷
|
||||
前端->>后端: POST /api/student/exam/{id}/submit
|
||||
后端->>后端: 自动判分
|
||||
后端-->>前端: 成绩 + 排名 + 答案解析
|
||||
```
|
||||
|
||||
### 4.2 管理流程（讲师）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[上传知识<br>DRAFT] --> B[发布知识<br>PUBLISHED]
|
||||
B --> C{有培训计划?}
|
||||
C -->|是| D[关联到培训计划]
|
||||
C -->|否| E[学员自由学习]
|
||||
|
||||
F[创建题目<br>DRAFT] --> G[发布题目<br>PUBLISHED]
|
||||
G --> H[组卷<br>手动/自动]
|
||||
H --> I[发布试卷<br>PUBLISHED]
|
||||
I --> J[创建考试<br>设置时间/次数]
|
||||
J --> K[指定考试对象<br>部门/小组/个人]
|
||||
D --> L[创建培训计划]
|
||||
J --> L
|
||||
L --> M[分配学员<br>部门/小组/个人]
|
||||
M --> N[发布培训计划]
|
||||
```
|
||||
|
||||
### 4.3 数据流转流程
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph 内容生产
|
||||
KM_CREATE[知识创建<br>km_knowledge DRAFT]
|
||||
KM_PUBLISH[发布知识<br>PUBLISHED]
|
||||
QS_CREATE[题目创建<br>ex_question DRAFT]
|
||||
QS_PUBLISH[发布题目<br>PUBLISHED]
|
||||
PP_CREATE[组卷<br>ex_paper + ex_paper_question]
|
||||
EX_CREATE[创建考试<br>ex_exam + ex_exam_target]
|
||||
TR_CREATE[培训计划<br>tr_plan + tr_plan_knowledge<br>+ tr_plan_exam + tr_plan_target]
|
||||
end
|
||||
|
||||
subgraph 学员消费
|
||||
LEARN[学习知识<br>→ km_knowledge_progress UPSERT]
|
||||
EXAM[参加考试<br>→ ex_exam_record 创建/更新]
|
||||
PROGRESS[进度计算<br>必修知识完成数 + 必考通过数]
|
||||
end
|
||||
|
||||
KM_CREATE --> KM_PUBLISH --> LEARN
|
||||
QS_CREATE --> QS_PUBLISH --> PP_CREATE --> EX_CREATE --> EXAM
|
||||
TR_CREATE --> LEARN
|
||||
TR_CREATE --> EXAM
|
||||
LEARN --> PROGRESS
|
||||
EXAM --> PROGRESS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据架构
|
||||
|
||||
### 5.1 核心数据实体（共19张表）
|
||||
|
||||
[SRC-SQL-01] [SRC-SQL-02]
|
||||
|
||||
| 数据域 | 表名 | 核心字段 | 说明 |
|
||||
|-------|------|---------|------|
|
||||
| **系统** | sys_center | id, name | 中心（最高层级） |
|
||||
| **系统** | sys_department | id, name, center_id | 部门（隶属中心） |
|
||||
| **系统** | sys_group | id, name, department_id | 小组（隶属部门） |
|
||||
| **系统** | sys_user | id, wx_userid, role(0/1/2), department_id, group_id, status | 用户（ADMIN/LECTURER/STUDENT） |
|
||||
| **知识库** | km_category | id, name, parent_id, department_id | 知识分类（多级树） |
|
||||
| **知识库** | km_knowledge | id, title, type(0文档/1视频), file_url, department_id, status(0/1/2) | 知识内容 |
|
||||
| **知识库** | km_knowledge_progress | id, user_id, knowledge_id, status, progress, duration, video_position, source, plan_id | 学习进度 |
|
||||
| **考试** | ex_question_category | id, name, parent_id, department_id | 题目分类 |
|
||||
| **考试** | ex_question | id, type(0/1/2), content, options(JSON), answer, analysis, status | 题目 |
|
||||
| **考试** | ex_paper | id, title, total_score, duration, pass_score, status | 试卷 |
|
||||
| **考试** | ex_paper_question | paper_id, question_id, score, sort_order | 试卷-题目关联 |
|
||||
| **考试** | ex_exam | id, title, paper_id, start_time, end_time, max_attempts, status(0/1/2) | 考试 |
|
||||
| **考试** | ex_exam_target | exam_id, target_type(0部门/1小组/2个人), target_id | 考试对象 |
|
||||
| **考试** | ex_exam_record | id, exam_id, user_id, attempt_no, score, passed, answers(JSON), status, version | 考试记录（含乐观锁） |
|
||||
| **培训** | tr_plan | id, title, start_date, end_date, department_id, status(0/1/2) | 培训计划 |
|
||||
| **培训** | tr_plan_knowledge | plan_id, knowledge_id, required, sort_order | 计划-知识关联 |
|
||||
| **培训** | tr_plan_exam | plan_id, exam_id, required, sort_order | 计划-考试关联（V1.0.1） |
|
||||
| **培训** | tr_plan_target | plan_id, target_type, target_id | 计划-对象 |
|
||||
| **培训** | tr_plan_progress | plan_id, user_id, knowledge_id, completed, complete_time | 旧版进度（已被 km_knowledge_progress 替代）|
|
||||
|
||||
### 5.2 实体关系图
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
sys_center ||--o{ sys_department : "中心下辖多个部门"
|
||||
sys_department ||--o{ sys_group : "部门下辖多个小组"
|
||||
sys_department ||--o{ sys_user : "用户属于部门"
|
||||
sys_group ||--o{ sys_user : "用户可归属小组"
|
||||
|
||||
sys_department ||--o{ km_category : "按部门隔离"
|
||||
km_category ||--o{ km_knowledge : "知识归属分类"
|
||||
sys_user ||--o{ km_knowledge_progress : "学员学习进度"
|
||||
km_knowledge ||--o{ km_knowledge_progress : "知识对应进度"
|
||||
|
||||
sys_department ||--o{ ex_question_category : "按部门隔离"
|
||||
ex_question_category ||--o{ ex_question : "题目归属分类"
|
||||
ex_paper ||--o{ ex_paper_question : "试卷包含多道题"
|
||||
ex_question ||--o{ ex_paper_question : "题目被多张试卷引用"
|
||||
ex_paper ||--|| ex_exam : "考试使用某试卷"
|
||||
ex_exam ||--o{ ex_exam_target : "考试指定对象"
|
||||
ex_exam ||--o{ ex_exam_record : "考试产生记录"
|
||||
sys_user ||--o{ ex_exam_record : "学员的考试记录"
|
||||
|
||||
tr_plan ||--o{ tr_plan_knowledge : "计划包含多个知识"
|
||||
tr_plan ||--o{ tr_plan_exam : "计划关联多场考试"
|
||||
tr_plan ||--o{ tr_plan_target : "计划分配给对象"
|
||||
km_knowledge ||--o{ tr_plan_knowledge : "知识被计划引用"
|
||||
ex_exam ||--o{ tr_plan_exam : "考试被计划引用"
|
||||
```
|
||||
|
||||
### 5.3 数据生命周期
|
||||
|
||||
| 数据类型 | 创建 | 有效态 | 失效态 | 删除方式 |
|
||||
|---------|------|-------|-------|---------|
|
||||
| 知识/题目/试卷 | DRAFT | PUBLISHED | OFFLINE | 逻辑删除（deleted=1） |
|
||||
| 考试 | NOT_STARTED | IN_PROGRESS | ENDED | 逻辑删除 |
|
||||
| 培训计划 | NOT_STARTED | IN_PROGRESS | ENDED | 逻辑删除 |
|
||||
| 考试记录 | IN_PROGRESS | SUBMITTED | 永久保留（取最高分） | 不删除 |
|
||||
| 学习进度 | NOT_STARTED | IN_PROGRESS | COMPLETED | UPSERT更新 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 权限与角色体系
|
||||
|
||||
### 6.1 角色定义
|
||||
|
||||
[SRC-FEAT-01：4.1 权限规则] [SRC-SQL-01：sys_user.role]
|
||||
|
||||
| 角色 | 枚举值（DB） | 数据范围 |
|
||||
|------|------------|---------|
|
||||
| 管理员 ADMIN | role=0 | 全平台（无部门隔离） |
|
||||
| 讲师 LECTURER | role=1 | 本部门（department_id匹配） |
|
||||
| 学员 STUDENT | role=2 | 本部门（只读；自己的进度/成绩） |
|
||||
|
||||
### 6.2 权限分层（按功能菜单）
|
||||
|
||||
| 菜单/功能 | ADMIN | LECTURER | STUDENT |
|
||||
|---------|-------|---------|---------|
|
||||
| 组织架构管理 | ✅ 全部 | ❌ | ❌ |
|
||||
| 员工管理 | ✅ 全部 | 👁️ 本部门只读 | ❌ |
|
||||
| 知识库-分类管理 | ✅ 全部 | ✅ 本部门 | ❌ |
|
||||
| 知识库-知识列表 | ✅ 全部 | ✅ 本部门（含草稿） | 👁️ 本部门已发布 |
|
||||
| 考题管理-题库分类 | ✅ | ✅ 本部门 | ❌ |
|
||||
| 考题管理-题目列表 | ✅ | ✅ 本部门 | ❌ |
|
||||
| 试卷管理 | ✅ | ✅ 本部门 | ❌ |
|
||||
| 考试管理 | ✅ | ✅ 本部门发布 | 👁️ 我的考试 |
|
||||
| 培训计划 | ✅ | ✅ 本部门创建/管理 | 👁️ 我的培训 |
|
||||
| 系统设置 | ✅ | ❌ | ❌ |
|
||||
| 工作台 | ✅ | ✅ | ✅（学员视图） |
|
||||
|
||||
[SRC-FEAT-01：8.1 角色菜单权限对照表]
|
||||
|
||||
### 6.3 控制逻辑
|
||||
|
||||
**认证层**：JWT Token 携带 userId + role，每次请求由 AuthInterceptor 解析验证。[SRC-CODE-01：common/interceptor/AuthInterceptor.java]
|
||||
|
||||
**授权层**：
|
||||
- 接口级：`@PreAuthorize` / SecurityConfig 按角色匹配路径（`/api/student/**` 仅 STUDENT）
|
||||
- 数据级：Service 层注入 `department_id` 过滤，讲师/学员查询一律追加 `WHERE department_id = ?`
|
||||
|
||||
**隔离规则**：
|
||||
- 4类数据（知识库、题库、试卷/考试、培训计划）均按 `department_id` 隔离
|
||||
- 管理员不注入部门过滤，讲师注入本部门，学员额外限制只查 PUBLISHED 状态
|
||||
|
||||
---
|
||||
|
||||
## 7. 系统扩展点分析
|
||||
|
||||
### 7.1 可扩展模块
|
||||
|
||||
| 扩展点 | 当前状态 | V2+ 扩展方向 |
|
||||
|-------|---------|------------|
|
||||
| 文件存储 | 本地文件系统 | 抽象 `FileStorageService` 接口 → MinIO/OSS 实现切换 |
|
||||
| 认证方式 | 企业微信 OAuth（账号密码作备选） | 可接入 SSO/LDAP |
|
||||
| 定时任务 | Spring @Scheduled（单机） | 可替换为 XXL-Job/SchedulerX 支持集群 |
|
||||
| 统计报表 | 无（V2规划） | 新增 `statistics` 模块，不影响现有模块 |
|
||||
| 通知 | 无（V2规划） | 可插入企业微信消息推送 |
|
||||
|
||||
### 7.2 可插拔能力
|
||||
|
||||
- **文档预览**：kkFileView / OnlyOffice 作为可选外部服务，knowledge 模块通过 URL 调用，可随时替换
|
||||
- **视频播放器**：video.js 为前端组件，与后端解耦，可替换
|
||||
- **批量导入**：EasyExcel 依赖已选型，可随时为题目/用户管理添加 Excel 导入功能
|
||||
|
||||
### 7.3 易变业务点
|
||||
|
||||
| 易变点 | 变化方向 | 影响范围 |
|
||||
|-------|---------|---------|
|
||||
| 培训完成判定逻辑（当前：必修知识+必考通过） | V2 可能增加签到、线下课时 | `TrainingProgressService.calculateProgress()` |
|
||||
| 知识学习完成判定（视频90%/文档时长） | 可能改为100%或按章节 | `KnowledgeLearningService.isCompleted()` |
|
||||
| 考试排名计算口径（当前：最高分排名 DENSE_RANK） | 可能改为平均分/最后一次 | SQL窗口函数，需同步修改 |
|
||||
| 组织架构层级（当前：中心→部门→小组三级） | 可能增减层级 | system 模块全面影响 |
|
||||
105
training/context/02-产品架构/03-系统能力模型.md
Normal file
105
training/context/02-产品架构/03-系统能力模型.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 系统能力模型总结 — 道路救援企业培训系统
|
||||
|
||||
> 版本：V1.0 | 生成日期：2026-04-07
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-API-01] [SRC-CODE-01]
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前系统具备的核心能力
|
||||
|
||||
| # | 能力名称 | 一句话描述 |
|
||||
|---|---------|----------|
|
||||
| C1 | **基于角色的访问控制（RBAC）** | 三种角色（管理员/讲师/学员）+ 部门级数据隔离，统一鉴权入口 |
|
||||
| C2 | **组织与人员管理** | 三级组织结构（中心→部门→小组）+ 用户生命周期管理 |
|
||||
| C3 | **知识资产管理** | 支持文档/视频两种类型的知识内容创建、状态发布和多级分类 |
|
||||
| C4 | **学习行为跟踪** | 防刷机制下的真实时长累计和进度记录（视频90%/文档时长判定） |
|
||||
| C5 | **在线考核** | 题库管理 + 手动/自动组卷 + 在线答题 + 客观题自动判分 |
|
||||
| C6 | **考试行为管控** | 时间窗口约束 + 次数限制 + 超时自动交卷 + 并发乐观锁保护 |
|
||||
| C7 | **培训任务编排** | 将知识+考试组织成有时间周期的培训计划，支持必修/选修/必考/选考四维属性 |
|
||||
| C8 | **培训进度可视化** | 实时计算学员对某培训计划的完成百分比（必修完成+必考通过） |
|
||||
| C9 | **成绩与排名** | 交卷后立即返回成绩+答案解析+实时排名（窗口函数，同分按时间早优先） |
|
||||
| C10 | **企业微信身份集成** | OAuth 登录打通企业微信用户体系，无需单独注册 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 能力依赖关系图
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
C10[C10 企业微信身份集成] --> C1
|
||||
C1[C1 RBAC + 部门隔离] --> C2
|
||||
C1 --> C3
|
||||
C1 --> C5
|
||||
C1 --> C7
|
||||
|
||||
C2[C2 组织人员管理] --> C7
|
||||
C3[C3 知识资产管理] --> C4
|
||||
C3 --> C7
|
||||
|
||||
C4[C4 学习行为跟踪] --> C8
|
||||
C5[C5 在线考核] --> C6
|
||||
C5 --> C9
|
||||
C6[C6 考试行为管控] --> C9
|
||||
C9[C9 成绩与排名] --> C8
|
||||
|
||||
C7[C7 培训任务编排] --> C4
|
||||
C7 --> C6
|
||||
C7 --> C8[C8 培训进度可视化]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 可复用能力清单
|
||||
|
||||
| 能力 | 复用场景 | 复用方式 |
|
||||
|-----|---------|---------|
|
||||
| C1 RBAC + 部门隔离 | 企业内任何需要角色权限 + 数据隔离的系统 | 提取 AuthInterceptor + UserContext + department_id 注入框架 |
|
||||
| C4 学习行为跟踪 | 其他类型内容（音频/直播回放/课件）的学习进度记录 | 抽象 `LearningTarget` 接口，替换完成判定策略（Strategy 模式） |
|
||||
| C5 在线考核 | 任意客观题在线测评场景（安全培训/合规考试等）| 题库+试卷+客观题判分为独立子系统，可独立部署 |
|
||||
| C6 考试行为管控 | 任何有"限时+限次"约束的在线测试 | ExamTakingService 中时间窗口/次数/乐观锁的组合控制逻辑 |
|
||||
| C9 成绩排名 | 任何需要实时排名的比赛/评测场景 | SQL 窗口函数 DENSE_RANK 模式，按需修改排序条件 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 平台级能力（多业务依赖的底层能力）
|
||||
|
||||
**C1 — RBAC + 部门数据隔离**
|
||||
- 所有业务模块（知识/考试/培训）均依赖此能力实现权限控制和数据隔离
|
||||
- 是系统安全性和多租户（多部门）能力的基础
|
||||
- 扩展方向：目前硬编码三个角色，V2 可改为动态角色配置
|
||||
|
||||
**C2 — 组织人员管理**
|
||||
- 每个业务操作都需要 `department_id`、`user_id`、`role` 三个属性
|
||||
- 是知识/考试/培训三大域的数据隔离依据来源
|
||||
- 扩展方向：当前三级固定结构，可抽象为 n 级通用树
|
||||
|
||||
**C10 — 企业微信身份集成**
|
||||
- 是唯一的用户来源（V1），后续接其他身份源也需通过此层
|
||||
- 扩展方向：抽象为 `IdentityProvider` 接口，支持插入 SSO/LDAP
|
||||
|
||||
---
|
||||
|
||||
## 5. 业务定制能力（特定场景才需要的能力）
|
||||
|
||||
| 能力 | 定制场景 | 为何不是平台级 |
|
||||
|-----|---------|-------------|
|
||||
| C3 知识资产管理（文档/视频类型） | 救援行业的操作手册、安全规范、视频讲解 | 内容类型固定（文档/视频），换行业可能需要不同类型 |
|
||||
| C4 学习行为防刷（视频90%/文档时长） | 强制"真实学习"的企业培训场景 | 完成判定规则是业务决策，C端平台通常不这么严格 |
|
||||
| C6 超时自动交卷 + 乐观锁 | 有严格时长限制的考试 | 休闲测试/知识问答类应用不需要这个复杂度 |
|
||||
| C7 培训任务编排（必修/选修/必考/选考四维）| 企业有组织要求的培训管理 | 自学平台不需要"强制必修"的约束 |
|
||||
| C9 成绩排名（DENSE_RANK + 同分按时间） | 部门内部考核的绩效排名 | 无竞争性考核场景（如自我测评）不需要排名 |
|
||||
|
||||
---
|
||||
|
||||
## 6. V2 能力规划缺口
|
||||
|
||||
当前 V1.0.1 尚未具备以下能力，是 V2 的扩展方向：
|
||||
|
||||
| 缺失能力 | 业务价值 | 实现复杂度 |
|
||||
|---------|---------|---------|
|
||||
| 统计报表中心（完成率/通过率/部门排名） | 管理层查看全局培训效果 | 中（新增 statistics 模块，读现有数据） |
|
||||
| 线下培训签到（扫码签到/签退） | 线上线下混合培训场景 | 中（需硬件支持） |
|
||||
| 错题本（自动归集错误题目） | 学员针对性复习 | 低（从 exam_record.answers 中提取 correct=false） |
|
||||
| 知识全文搜索 | 快速查找内容 | 高（需引入 Elasticsearch 或 MySQL FULLTEXT） |
|
||||
| 奖励体系（积分/勋章/排行榜） | 提升学习积极性 | 中（新增独立模块） |
|
||||
| 证书管理 | 培训完成凭证 | 低（基于培训计划完成状态生成 PDF） |
|
||||
110
training/context/03-功能模块/01-认证模块.md
Normal file
110
training/context/03-功能模块/01-认证模块.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 认证模块（auth）
|
||||
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-API-01] [SRC-CODE-01：module/auth/]
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
- **模块目标**：负责用户身份验证（企业微信OAuth + 账号密码备选）和 JWT Token 的签发、校验，为所有其他模块提供鉴权基础。
|
||||
- **解决问题**：500人规模的企业内部系统，需要统一身份验证入口，并将身份与角色绑定，为下游数据隔离提供 `userId + role + departmentId` 上下文。
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能清单
|
||||
|
||||
[SRC-API-01：四、API 接口设计 / SRC-CODE-01：module/auth/]
|
||||
|
||||
| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
|
||||
|---------|---------|------|------|---------|
|
||||
| 企业微信 OAuth 登录 | 通过企业微信授权 code 换取用户身份，查找系统用户，签发 JWT | wx_code | JWT Token + 用户信息（LoginResponse） | system（查sys_user） |
|
||||
| 账号密码登录（备选） | 用用户名+密码登录，BCrypt 验证密码 | username, password | JWT Token + 用户信息 | system（查sys_user） |
|
||||
| 获取当前用户信息 | 解析 Token 返回用户基本信息 | Authorization Header | UserInfoResponse | - |
|
||||
| 微信小程序登录（预留） | 通过小程序 code 获取用户信息 | WechatLoginRequest | JWT Token | system |
|
||||
| Token 携带与拦截 | AuthInterceptor 拦截所有受保护请求，提取 Token 注入 UserContext | Authorization: Bearer {token} | UserContext（ThreadLocal） | - |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心逻辑
|
||||
|
||||
### 3.1 业务规则
|
||||
|
||||
- 企业微信登录路径：前端传 code → 后端调 weixin-java-cp SDK 换 `access_token` → 获取 `wx_userid` → 查 `sys_user.wx_userid` 匹配 → 用户不存在则返回错误（不自动注册）[SRC-FEAT-01]
|
||||
- JWT Payload 包含：userId、role、departmentId，有效期由配置决定
|
||||
- 密码存储：BCrypt 加密（Spring Security 6.x），初始管理员密码 `admin123` 已预置 [SRC-SQL-01：5.4]
|
||||
|
||||
### 3.2 校验逻辑
|
||||
|
||||
| 校验项 | 规则 | 失败响应 |
|
||||
|-------|------|---------|
|
||||
| wx_userid 是否存在于 sys_user | 必须已由管理员录入 | 返回错误：用户未录入，请联系管理员 |
|
||||
| sys_user.status | 必须为 0（启用） | 返回错误：账号已禁用 |
|
||||
| Token 有效性 | 未过期、签名正确 | 返回 401 |
|
||||
| 受保护接口 Token 缺失 | 无 Authorization Header | 返回 401 |
|
||||
|
||||
### 3.3 状态流转
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 未认证
|
||||
未认证 --> 已认证 : 登录成功（JWT签发）
|
||||
已认证 --> 未认证 : Token过期 / 主动登出
|
||||
已认证 --> 已认证 : Token续期（如有配置）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据结构
|
||||
|
||||
### 4.1 涉及数据表
|
||||
|
||||
**sys_user**（读取，不由本模块创建）[SRC-SQL-01]
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 用户主键 |
|
||||
| wx_userid | VARCHAR(100) | 企业微信用户ID（唯一索引 uk_wx_userid） |
|
||||
| username | VARCHAR(50) | 账号密码登录用账号（唯一索引 uk_username） |
|
||||
| password | VARCHAR(100) | BCrypt加密密码 |
|
||||
| role | TINYINT | 0-管理员 / 1-讲师 / 2-学员 |
|
||||
| department_id | BIGINT | 所属部门ID（会注入 JWT Payload） |
|
||||
| status | TINYINT | 0-启用 / 1-禁用 |
|
||||
|
||||
### 4.2 DTO/VO 定义
|
||||
|
||||
[SRC-CODE-01：module/auth/dto/]
|
||||
|
||||
| 类名 | 方向 | 关键字段 |
|
||||
|------|------|---------|
|
||||
| LoginRequest | 入参 | username, password |
|
||||
| WechatLoginRequest | 入参 | code（企业微信授权码） |
|
||||
| LoginResponse | 出参 | token, userId, realName, role, departmentId |
|
||||
| UserInfoResponse | 出参 | 同 LoginResponse（从 Token 解析） |
|
||||
|
||||
---
|
||||
|
||||
## 5. 对外接口
|
||||
|
||||
[SRC-API-01]
|
||||
|
||||
| API 名称 | 方法 | 路径 | 权限 |
|
||||
|---------|------|------|------|
|
||||
| 企业微信登录 | POST | /api/auth/wechat/login | 公开 |
|
||||
| 账号密码登录 | POST | /api/auth/login | 公开 |
|
||||
| 获取当前用户 | GET | /api/auth/me | 需 Token |
|
||||
|
||||
**事件机制**：登录成功后，UserContext（ThreadLocal）持有用户信息，供同请求链路的所有 Service 使用，请求结束后清除。[SRC-CODE-01：common/context/UserContextHolder.java]
|
||||
|
||||
---
|
||||
|
||||
## 6. 异常与边界处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| 企业微信 API 调用超时/失败 | 返回 503，提示"企业微信服务暂时不可用，请稍后重试" |
|
||||
| 企业微信 code 已使用（重放） | 企业微信 SDK 返回错误，转化为 400 |
|
||||
| 用户 wx_userid 存在但账号被禁用（status=1） | 返回 403，提示"账号已禁用，请联系管理员" |
|
||||
| sys_user 中无对应 wx_userid | 返回 403，提示"用户未录入系统，请联系管理员" |
|
||||
| Token 格式错误（非JWT） | AuthInterceptor 捕获，返回 401 |
|
||||
| Token 过期 | AuthInterceptor 捕获，返回 401，前端跳转登录页 |
|
||||
| 并发登录（同一账号多端） | 当前设计无限制，多端独立 Token 有效 |
|
||||
165
training/context/03-功能模块/02-系统管理模块.md
Normal file
165
training/context/03-功能模块/02-系统管理模块.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 系统管理模块（system）
|
||||
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-SQL-01] [SRC-CODE-01：module/system/]
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
- **模块目标**：管理企业的组织架构（中心→部门→小组三级）和用户生命周期（录入、角色分配、状态管理），为所有业务模块的部门数据隔离提供基础。
|
||||
- **解决问题**：3-5名管理员管理约500人的组织结构，人员分配到正确部门和角色，是知识库/考试/培训数据隔离的前置条件。
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能清单
|
||||
|
||||
[SRC-FEAT-01：模块一] [SRC-CODE-01：module/system/]
|
||||
|
||||
| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
|
||||
|---------|---------|------|------|---------|
|
||||
| 中心管理（CRUD） | 创建/修改/删除最高级组织单元"中心" | CenterDTO（name, sort_order） | CenterVO | - |
|
||||
| 部门管理（CRUD） | 在中心下创建/修改/删除部门，每中心最多8个部门 | DepartmentDTO（name, center_id） | DepartmentVO | - |
|
||||
| 小组管理（CRUD） | 在部门下创建/修改/删除小组，每部门最多10个小组 | GroupDTO（name, department_id） | GroupVO | - |
|
||||
| 组织树查询 | 一次性返回完整组织树（中心→部门→小组层级） | - | OrgTreeVO（树形结构） | - |
|
||||
| 员工列表查询 | 分页查询员工，支持按部门/角色/姓名筛选 | UserQueryDTO | PageResult<UserVO> | - |
|
||||
| 员工录入 | 管理员手动录入员工信息，绑定企业微信 userid | UserDTO（wx_userid, real_name, role, department_id…） | UserVO | - |
|
||||
| 员工信息修改 | 修改员工姓名、部门、角色、小组归属 | UserDTO | UserVO | - |
|
||||
| 员工禁用/启用 | 切换员工账号状态（0启用/1禁用） | userId, status | - | auth（下次登录校验） |
|
||||
| 密码重置 | 管理员重置员工的账号密码（BCrypt） | PasswordDTO（userId, newPassword） | - | auth |
|
||||
| 讲师查看本部门员工 | 讲师可查看本部门员工列表（只读，无编辑权限） | department_id（从Token注入） | PageResult<UserVO> | auth |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心逻辑
|
||||
|
||||
### 3.1 业务规则
|
||||
|
||||
[SRC-FEAT-01：模块一]
|
||||
|
||||
- **层级约束**：中心 → 部门（一个中心最多8个部门）→ 小组（一个部门最多10个小组），超限不允许创建
|
||||
- **角色约束**：用户角色只能为 ADMIN(0) / LECTURER(1) / STUDENT(2) 三种，创建时必填
|
||||
- **部门归属**：LECTURER 和 STUDENT 必须归属某部门（department_id 不可为空），ADMIN 可无部门
|
||||
- **逻辑删除**：所有实体使用 `deleted=1` 软删除，禁止物理删除，防止外键依赖失效
|
||||
- **员工录入方式**：V1 仅支持管理员手动逐条录入，不支持批量导入（V2 规划 EasyExcel 导入）
|
||||
|
||||
### 3.2 校验逻辑
|
||||
|
||||
| 校验项 | 规则 | 失败响应 |
|
||||
|-------|------|---------|
|
||||
| 部门数量上限 | 同一 center_id 下 deleted=0 的部门数 ≤ 8 | 400：该中心部门数已达上限(8个) |
|
||||
| 小组数量上限 | 同一 department_id 下 deleted=0 的小组数 ≤ 10 | 400：该部门小组数已达上限(10个) |
|
||||
| wx_userid 唯一 | sys_user.wx_userid 全局唯一（uk_wx_userid 索引） | 400：该企业微信账号已录入 |
|
||||
| username 唯一 | sys_user.username 全局唯一（uk_username 索引） | 400：用户名已存在 |
|
||||
| 讲师数据隔离 | LECTURER 调用员工列表时，强制追加 department_id = 当前用户部门 | 自动过滤，不报错 |
|
||||
| 删除有子项的上级 | 删除中心前，其下所有部门必须已删除；删除部门前，其下所有小组和用户必须已处理 | 400：请先删除部门下的小组和员工 |
|
||||
|
||||
### 3.3 状态流转
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 启用 : 员工录入时默认 status=0
|
||||
启用 --> 禁用 : 管理员操作禁用
|
||||
禁用 --> 启用 : 管理员操作启用
|
||||
禁用 --> 已删除 : 逻辑删除（deleted=1）
|
||||
启用 --> 已删除 : 逻辑删除（deleted=1）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据结构
|
||||
|
||||
[SRC-SQL-01：一、系统管理模块]
|
||||
|
||||
### 4.1 涉及数据表
|
||||
|
||||
**sys_center**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) | 中心名称 |
|
||||
| sort_order | INT DEFAULT 0 | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除（0/1） |
|
||||
|
||||
**sys_department**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) | 部门名称 |
|
||||
| center_id | BIGINT NOT NULL | 所属中心（idx_center_id 索引） |
|
||||
| sort_order | INT | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
**sys_group**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) | 小组名称 |
|
||||
| department_id | BIGINT NOT NULL | 所属部门（idx_department_id 索引） |
|
||||
| sort_order | INT | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
**sys_user**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| wx_userid | VARCHAR(100) | 企业微信 userid（唯一） |
|
||||
| username | VARCHAR(50) NOT NULL | 账号（唯一） |
|
||||
| password | VARCHAR(100) | BCrypt 加密密码 |
|
||||
| real_name | VARCHAR(50) NOT NULL | 真实姓名 |
|
||||
| phone | VARCHAR(20) | 手机号 |
|
||||
| avatar | VARCHAR(255) | 头像 URL |
|
||||
| role | TINYINT NOT NULL | 0-管理员 / 1-讲师 / 2-学员 |
|
||||
| department_id | BIGINT | 所属部门（可空，ADMIN 用） |
|
||||
| group_id | BIGINT | 所属小组（可空） |
|
||||
| status | TINYINT DEFAULT 0 | 0-启用 / 1-禁用 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
### 4.2 数据关联
|
||||
|
||||
- `sys_user.department_id` → `sys_department.id`（无外键约束，逻辑关联）
|
||||
- `sys_user.group_id` → `sys_group.id`（可空）
|
||||
- `sys_department.center_id` → `sys_center.id`
|
||||
|
||||
---
|
||||
|
||||
## 5. 对外接口
|
||||
|
||||
[SRC-CODE-01：module/system/controller/]
|
||||
|
||||
| API 名称 | 方法 | 路径 | 权限 |
|
||||
|---------|------|------|------|
|
||||
| 获取组织树 | GET | /api/system/org/tree | ADMIN |
|
||||
| 查询中心列表 | GET | /api/system/center | ADMIN |
|
||||
| 创建中心 | POST | /api/system/center | ADMIN |
|
||||
| 修改中心 | PUT | /api/system/center/{id} | ADMIN |
|
||||
| 删除中心 | DELETE | /api/system/center/{id} | ADMIN |
|
||||
| 查询部门列表 | GET | /api/system/department | ADMIN |
|
||||
| 创建部门 | POST | /api/system/department | ADMIN |
|
||||
| 修改部门 | PUT | /api/system/department/{id} | ADMIN |
|
||||
| 删除部门 | DELETE | /api/system/department/{id} | ADMIN |
|
||||
| 查询小组列表 | GET | /api/system/group | ADMIN |
|
||||
| 创建小组 | POST | /api/system/group | ADMIN |
|
||||
| 修改小组 | PUT | /api/system/group/{id} | ADMIN |
|
||||
| 删除小组 | DELETE | /api/system/group/{id} | ADMIN |
|
||||
| 查询员工列表 | GET | /api/system/user | ADMIN(全部) / LECTURER(本部门只读) |
|
||||
| 创建员工 | POST | /api/system/user | ADMIN |
|
||||
| 修改员工 | PUT | /api/system/user/{id} | ADMIN |
|
||||
| 禁用/启用员工 | PUT | /api/system/user/{id}/status | ADMIN |
|
||||
| 重置密码 | PUT | /api/system/user/{id}/password | ADMIN |
|
||||
|
||||
---
|
||||
|
||||
## 6. 异常与边界处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| 删除有下级的中心/部门 | 校验子项是否全部删除，否则返回 400 + 提示 |
|
||||
| 部门/小组数量超限 | 严格校验上限（8/10），超出返回 400 |
|
||||
| 员工 wx_userid 重复 | 唯一索引捕获 DuplicateKeyException，友好提示 |
|
||||
| LECTURER 访问其他部门员工 | AuthInterceptor / Service 层强制 department_id 过滤，返回空列表 |
|
||||
| 管理员误操作禁用自己 | [ASSUMPTION] PRD 未明确说明是否限制，建议禁止禁用最后一个 ADMIN |
|
||||
| 员工转移部门 | 修改 department_id 即可，但其历史知识进度/考试记录中的 department_id 为冗余字段不随之更新 |
|
||||
205
training/context/03-功能模块/03-知识库模块.md
Normal file
205
training/context/03-功能模块/03-知识库模块.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# 知识库模块（knowledge）
|
||||
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-FEAT-02] [SRC-SQL-01] [SRC-SQL-02] [SRC-API-01] [SRC-CODE-01：module/knowledge/]
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
- **模块目标**：管理企业的结构化知识资产，支持文档和视频两种内容类型的上传、分类管理、状态发布，并记录学员的个人学习进度。
|
||||
- **解决问题**：解决救援知识依赖口口相传的问题；同时为培训计划提供可引用的学习内容，并跟踪学员是否真实完成学习（防刷机制）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能清单
|
||||
|
||||
[SRC-FEAT-01：模块二] [SRC-FEAT-02：3.2 知识学习]
|
||||
|
||||
| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
|
||||
|---------|---------|------|------|---------|
|
||||
| 知识分类管理 | 创建/修改/删除多级分类树，按部门隔离 | CategoryDTO（name, parent_id, department_id） | CategoryVO | system（部门） |
|
||||
| 知识分类树查询 | 返回树形结构的分类目录 | department_id | List<CategoryVO>（树） | - |
|
||||
| 知识内容 CRUD | 创建/修改/删除知识（文档/视频），状态为草稿时可修改 | KnowledgeDTO（title, type, file_url, category_id…） | KnowledgeVO | system |
|
||||
| 文件上传 | 上传 PDF/Word/Excel/PPT/视频文件，返回文件 URL | MultipartFile | FileDTO（url, fileName, size, type） | 文件存储服务 |
|
||||
| 知识发布/下架 | 变更知识状态（草稿→发布/发布→下架/下架→再发布）| knowledgeId, action | - | - |
|
||||
| 知识列表查询（讲师端） | 管理端分页查询，可查所有状态，含草稿 | KnowledgeQueryDTO（category_id, status, keyword） | PageResult<KnowledgeVO> | - |
|
||||
| 知识列表查询（学员端） | 只查 PUBLISHED 状态，携带个人学习状态 | department_id, KnowledgeQueryDTO | PageResult<KnowledgeVO + 学习状态> | auth |
|
||||
| 知识在线预览 | 文档在线预览（PDF/Word等）、视频在线播放 | knowledgeId | 文件 URL / 预览链接 | 文件存储/文档预览服务 |
|
||||
| 开始学习 | 创建或获取学习进度记录，记录首次学习时间 | knowledgeId, [source, planId] | - | auth |
|
||||
| 更新学习进度 | 定时上报学习进度（每60秒），累加时长，判断完成 | ProgressUpdateDTO（duration, progress, videoPosition, source, planId） | - | training（若来源=TRAINING） |
|
||||
| 完成学习 | 前端显式标记完成（文档）| knowledgeId | - | - |
|
||||
| 查询学习进度 | 查询学员对某知识/某批知识的学习状态 | userId/knowledgeIds | List<KnowledgeProgressVO> | - |
|
||||
| 引用保护检查 | 检查知识是否被培训计划引用，下架前警告 | knowledgeId | Boolean + 引用计划数 | training |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心逻辑
|
||||
|
||||
### 3.1 业务规则
|
||||
|
||||
[SRC-FEAT-01：4.5 引用保护规则] [SRC-API-01：5.1 学习进度更新流程]
|
||||
|
||||
**内容状态规则**：
|
||||
- 草稿（DRAFT=0）：只有讲师和管理员可见，可自由修改
|
||||
- 已发布（PUBLISHED=1）：全部门学员可见，处于此状态时不可修改内容（需先下架）
|
||||
- 已下架（OFFLINE=2）：学员不可见，可重新上架或继续修改后再发布
|
||||
|
||||
**学习进度完成判定规则**：
|
||||
- **视频类**：播放进度 ≥ 90% 时，status 自动变更为 COMPLETED
|
||||
- **文档类**：累计学习时长 ≥ 预估阅读时间（按文件大小估算，具体算法在 `calculateEstimatedTime()`）时，status 变更为 COMPLETED
|
||||
- 两种类型均支持多次学习，完成后不会重置；时长可继续累加
|
||||
|
||||
**防刷机制（活跃检测）**：
|
||||
- 前端 ActivityDetector 监听 mousemove/click/scroll/keypress 事件
|
||||
- 60秒无活动判定为非活跃，停止本地计时器，不上报进度
|
||||
- 恢复活跃后重新计时
|
||||
|
||||
**多标签页防重**：
|
||||
- BroadcastChannel API 实现：同一知识在多个 Tab 打开时，检测到重复后关闭后来的 Tab [SRC-API-01：6.2]
|
||||
|
||||
**部门数据隔离**：
|
||||
- 所有知识查询一律追加 `WHERE department_id = [当前用户部门]`
|
||||
- 分类也按 department_id 隔离
|
||||
|
||||
**引用保护**：
|
||||
- 知识下架前，需检查 `tr_plan_knowledge` 中是否有关联；若有，提示警告，用户确认后方可下架
|
||||
|
||||
### 3.2 校验逻辑
|
||||
|
||||
| 校验项 | 规则 | 失败响应 |
|
||||
|-------|------|---------|
|
||||
| 文件类型 | 文档：PDF/Word/Excel/PPT；视频：MP4等常见格式 | 400：不支持的文件格式 |
|
||||
| 文件大小 | [ASSUMPTION] PRD 提及限制大文件，具体上限需配置，建议文档 ≤100MB，视频 ≤2GB | 400：文件超出大小限制 |
|
||||
| 知识状态变更 | PUBLISHED 状态下不允许修改内容字段（标题/文件），只允许下架操作 | 400：已发布知识不可修改，请先下架 |
|
||||
| 学习进度上报频率 | 前端每60秒上报一次，后端不做频率限制（允许补报） | - |
|
||||
| 视频播放进度合理性 | `video_position ≤ 视频总时长`（[ASSUMPTION] 后端当前未做服务端校验，PRD 明确属于风险项） | 暂无服务端拦截 |
|
||||
| 分类隶属 | 知识的 category_id 必须属于同一 department_id 的分类 | 400：分类不存在或无权限 |
|
||||
|
||||
### 3.3 状态流转
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> DRAFT : 创建知识（可新增/修改/删除）
|
||||
DRAFT --> PUBLISHED : 讲师发布
|
||||
PUBLISHED --> OFFLINE : 讲师下架（引用警告确认）
|
||||
OFFLINE --> PUBLISHED : 讲师重新上架
|
||||
OFFLINE --> DRAFT : 重新编辑后回到草稿 [ASSUMPTION]
|
||||
DRAFT --> [*] : 逻辑删除
|
||||
|
||||
note right of PUBLISHED : 学员可见\n不可修改内容
|
||||
note right of DRAFT : 仅讲师/管理员可见
|
||||
note right of OFFLINE : 学员不可见\n可编辑
|
||||
```
|
||||
|
||||
**学习进度状态流转**：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> NOT_STARTED : 知识发布，学员尚未打开
|
||||
NOT_STARTED --> IN_PROGRESS : 调用"开始学习"接口
|
||||
IN_PROGRESS --> IN_PROGRESS : 每次上报进度（时长累加）
|
||||
IN_PROGRESS --> COMPLETED : 视频≥90% 或 文档时长达标
|
||||
COMPLETED --> IN_PROGRESS : 再次学习（时长继续累加，状态不回退）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据结构
|
||||
|
||||
[SRC-SQL-01：二、知识库模块] [SRC-SQL-02]
|
||||
|
||||
### 4.1 涉及数据表
|
||||
|
||||
**km_category**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) NOT NULL | 分类名称 |
|
||||
| parent_id | BIGINT DEFAULT 0 | 父分类（0=顶级） |
|
||||
| department_id | BIGINT NOT NULL | 所属部门（部门隔离键） |
|
||||
| sort_order | INT | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
**km_knowledge**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| title | VARCHAR(200) NOT NULL | 标题 |
|
||||
| description | TEXT | 描述/摘要 |
|
||||
| category_id | BIGINT | 所属分类（可空） |
|
||||
| type | TINYINT NOT NULL | 0-文档 / 1-视频 |
|
||||
| file_name | VARCHAR(255) | 文件名 |
|
||||
| file_url | VARCHAR(500) | 文件 URL |
|
||||
| file_size | BIGINT | 文件大小（字节） |
|
||||
| file_type | VARCHAR(20) | 文件后缀（pdf/mp4…） |
|
||||
| department_id | BIGINT NOT NULL | 所属部门（隔离键，有 idx） |
|
||||
| status | TINYINT DEFAULT 0 | 0-草稿 / 1-已发布 / 2-已下架 |
|
||||
| creator_id | BIGINT NOT NULL | 创建人 |
|
||||
| publish_time | DATETIME | 发布时间 |
|
||||
| view_count | INT | 浏览次数 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
**km_knowledge_progress**（学员学习进度）[SRC-SQL-02]
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| user_id | BIGINT NOT NULL | 学员ID |
|
||||
| knowledge_id | BIGINT NOT NULL | 知识ID |
|
||||
| department_id | BIGINT NOT NULL | 部门（冗余，用于分区查询） |
|
||||
| status | VARCHAR(20) | NOT_STARTED / IN_PROGRESS / COMPLETED |
|
||||
| progress | INT | 进度百分比（0~100） |
|
||||
| duration | BIGINT | 累计学习时长（秒） |
|
||||
| video_position | BIGINT | 视频播放位置（秒，仅视频） |
|
||||
| source | VARCHAR(20) | FREE / TRAINING |
|
||||
| plan_id | BIGINT | 关联培训计划（source=TRAINING 时有值） |
|
||||
| start_time | DATETIME | 首次学习时间 |
|
||||
| complete_time | DATETIME | 完成时间 |
|
||||
| 唯一约束 | uk_user_knowledge | (user_id, knowledge_id) 唯一 |
|
||||
|
||||
### 4.2 数据关联
|
||||
|
||||
- `km_knowledge.category_id` → `km_category.id`
|
||||
- `km_knowledge.department_id` = `km_category.department_id`（同部门隔离）
|
||||
- `km_knowledge_progress.user_id` → `sys_user.id`
|
||||
- `km_knowledge_progress.plan_id` → `tr_plan.id`（可空）
|
||||
|
||||
---
|
||||
|
||||
## 5. 对外接口
|
||||
|
||||
[SRC-API-01：4.3 知识学习接口] [SRC-CODE-01：module/knowledge/controller/]
|
||||
|
||||
| API 名称 | 方法 | 路径 | 权限 |
|
||||
|---------|------|------|------|
|
||||
| 查询知识分类树 | GET | /api/knowledge/category/tree | LECTURER/ADMIN |
|
||||
| 创建分类 | POST | /api/knowledge/category | LECTURER/ADMIN |
|
||||
| 修改分类 | PUT | /api/knowledge/category/{id} | LECTURER/ADMIN |
|
||||
| 删除分类 | DELETE | /api/knowledge/category/{id} | LECTURER/ADMIN |
|
||||
| 查询知识列表（管理端） | GET | /api/knowledge | LECTURER/ADMIN |
|
||||
| 创建知识 | POST | /api/knowledge | LECTURER/ADMIN |
|
||||
| 修改知识 | PUT | /api/knowledge/{id} | LECTURER/ADMIN |
|
||||
| 发布/下架知识 | PUT | /api/knowledge/{id}/status | LECTURER/ADMIN |
|
||||
| 删除知识 | DELETE | /api/knowledge/{id} | LECTURER/ADMIN |
|
||||
| 文件上传 | POST | /api/knowledge/upload | LECTURER/ADMIN |
|
||||
| 学员-知识列表 | GET | /api/student/knowledge | STUDENT |
|
||||
| 学员-知识详情 | GET | /api/student/knowledge/{id} | STUDENT |
|
||||
| 学员-开始学习 | POST | /api/student/knowledge/{id}/start | STUDENT |
|
||||
| 学员-更新进度 | POST | /api/student/knowledge/{id}/progress | STUDENT |
|
||||
| 学员-标记完成 | POST | /api/student/knowledge/{id}/complete | STUDENT |
|
||||
|
||||
---
|
||||
|
||||
## 6. 异常与边界处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| 已发布知识被下架，同时培训计划正引用 | 弹出确认警告，显示引用该知识的培训计划数量，用户确认后方可下架 |
|
||||
| 文件上传失败（存储服务不可用） | 返回 503，前端提示"文件上传失败，请稍后重试" |
|
||||
| 学员学习已下架的知识（在培训计划中） | [ASSUMPTION] PRD 未明确，建议：关联进培训计划的知识下架后，学员仍可查看历史进度但不可重新打开 |
|
||||
| km_knowledge_progress 并发 UPSERT（同一学员多标签页） | 唯一约束 uk_user_knowledge 防止重复插入；多标签页同步由前端 BroadcastChannel 控制关闭重复 Tab |
|
||||
| 视频播放中途退出 | 下次进入从 video_position 断点续播 |
|
||||
| 学习进度上报时网络中断 | 前端重试，后端幂等（UPSERT 语义，重复上报取最大值或继续累加） |
|
||||
| 分类下有知识时删除分类 | 检查该分类下是否有 deleted=0 的知识，若有则拒绝：400 请先移除分类下的知识 |
|
||||
253
training/context/03-功能模块/04-考试模块.md
Normal file
253
training/context/03-功能模块/04-考试模块.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 考试模块（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 状态流转
|
||||
|
||||
**内容状态（题目/试卷）**：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> DRAFT : 创建
|
||||
DRAFT --> PUBLISHED : 发布（题目需有 analysis）
|
||||
PUBLISHED --> OFFLINE : 下架（引用保护确认）
|
||||
OFFLINE --> PUBLISHED : 重新上架
|
||||
DRAFT --> [*] : 逻辑删除
|
||||
```
|
||||
|
||||
**考试状态**：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> NOT_STARTED : 创建考试（start_time 未到）
|
||||
NOT_STARTED --> IN_PROGRESS : 到达 start_time（自动或手动）
|
||||
IN_PROGRESS --> ENDED : 到达 end_time（自动或手动结束）
|
||||
ENDED --> [*] : 逻辑删除
|
||||
```
|
||||
|
||||
**考试记录状态**：
|
||||
|
||||
```mermaid
|
||||
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 记录恢复，重新进入走断点续考流程 |
|
||||
196
training/context/03-功能模块/05-培训计划模块.md
Normal file
196
training/context/03-功能模块/05-培训计划模块.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 培训计划模块（training）
|
||||
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-FEAT-02] [SRC-SQL-01] [SRC-API-01] [SRC-CODE-01：module/training/]
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
- **模块目标**：将知识内容和考试任务组合成有时间范围的培训计划，分配给指定学员，并跟踪每位学员的完成进度。
|
||||
- **解决问题**：组织端无法跟踪员工是否真正完成学习目标；培训计划模块实现"分配→执行→进度可视"的闭环管理。
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能清单
|
||||
|
||||
[SRC-FEAT-01：模块六] [SRC-FEAT-02：3.4 我的培训] [SRC-API-01：4.5]
|
||||
|
||||
| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
|
||||
|---------|---------|------|------|---------|
|
||||
| 创建培训计划 | 设置计划基本信息（名称/描述/时间范围/所属部门） | TrainingPlanQueryDTO（title, start_date, end_date） | TrainingPlanVO | system |
|
||||
| 关联知识内容 | 在培训计划中添加多个知识，设置必修/选修和排序 | plan_id, [{knowledge_id, required, sort_order}] | - | knowledge |
|
||||
| 关联考试任务 | 在培训计划中添加多个考试，设置必考/选考和排序（V1.0.1+）| plan_id, [{exam_id, required, sort_order}] | - | exam |
|
||||
| 分配培训对象 | 指定培训计划的参与者（部门/小组/个人） | plan_id, [{target_type, target_id}] | - | system |
|
||||
| 培训计划列表（讲师端） | 查询本部门的培训计划，含状态和统计信息 | 分页参数 | PageResult<TrainingPlanVO> | - |
|
||||
| 培训计划详情（讲师端） | 查看计划详情，含关联知识/考试/对象/进度汇总 | planId | TrainingPlanDetailVO | - |
|
||||
| 更新/删除培训计划 | 修改计划信息（未开始时可修改，进行中时受限）| planId, TrainingPlanQueryDTO | - | - |
|
||||
| 学员-我的培训列表 | 查询分配给当前学员的培训计划（进行中优先） | - | PageResult<TrainingPlanVO + 进度> | auth |
|
||||
| 学员-培训详情 | 查看某培训计划详情：课程列表+学习状态+考试列表+通过状态 | planId | TrainingDetailVO | knowledge, exam |
|
||||
| 进度计算 | 按必修知识完成数 + 必考通过数 / 总必修项 计算进度% | planId, userId | Integer（0~100） | knowledge, exam |
|
||||
| 知识进度同步 | 学员学习某知识时，若 source=TRAINING 则同步更新 tr_plan_progress | planId, userId, knowledgeId | - | knowledge |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心逻辑
|
||||
|
||||
### 3.1 业务规则
|
||||
|
||||
[SRC-FEAT-01：模块六] [SRC-API-01：5.4]
|
||||
|
||||
**培训计划状态自动流转**：
|
||||
- `tr_plan.status` 根据 `start_date` / `end_date` 与当前日期比较自动判定：
|
||||
- `NOW() < start_date` → NOT_STARTED
|
||||
- `start_date ≤ NOW() ≤ end_date` → IN_PROGRESS
|
||||
- `NOW() > end_date` → ENDED
|
||||
- [ASSUMPTION] 状态字段在查询时实时计算，或由定时任务定期刷新（PRD 未明确）
|
||||
|
||||
**培训进度计算公式**（V1.0.1）[SRC-API-01：5.4]：
|
||||
```
|
||||
progress% = (必修知识完成数 + 必考考试通过数) / (必修知识总数 + 必考考试总数) × 100
|
||||
```
|
||||
- 必修知识完成：`km_knowledge_progress.status = COMPLETED` 且 `plan_id = 当前计划`
|
||||
- 必考通过：在 `tr_plan_exam` 中 `required=1` 的考试，学员在 `ex_exam_record` 中存在 `passed=1` 的记录
|
||||
- 选修知识/选考考试不计入进度（但在详情页展示）
|
||||
- 总必修项为 0 时，进度 = 100%（无内容的计划视为自动完成）
|
||||
|
||||
**知识完成与培训进度联动**：
|
||||
- 学员调用 `knowledge.updateProgress()` 时，若 `source=TRAINING` 且 `planId != null`：
|
||||
1. 更新 `km_knowledge_progress`
|
||||
2. 若 status 变为 COMPLETED，则更新 `tr_plan_progress`（plan_id, user_id, knowledge_id 唯一记录）
|
||||
|
||||
**考试通过与培训进度联动**：
|
||||
- 学员考试提交后，`TrainingProgressService` 查询该 exam_id 被哪些计划引用（`tr_plan_exam`），若有关联且 `passed=1`，则重新计算相关计划的进度（或标记为需要刷新）
|
||||
|
||||
**多对象分配逻辑**：
|
||||
- 分配对象类型支持 DEPARTMENT(0) / GROUP(1) / USER(2) 混合
|
||||
- 当指定 DEPARTMENT 时，该部门下所有 STUDENT 账号都被纳入
|
||||
- 当指定 GROUP 时，该小组所有成员纳入
|
||||
- 已被纳入的学员在查询时去重（多路径覆盖同一人不重复统计）
|
||||
|
||||
### 3.2 校验逻辑
|
||||
|
||||
| 校验项 | 规则 | 失败响应 |
|
||||
|-------|------|---------|
|
||||
| 培训时间范围 | start_date < end_date | 400：培训结束日期必须晚于开始日期 |
|
||||
| 关联知识状态 | 关联到计划的知识必须是 PUBLISHED 状态 | 400：请先发布知识再关联到培训计划 |
|
||||
| 关联考试状态 | 关联到计划的考试必须是 IN_PROGRESS 或 NOT_STARTED | 400：已结束的考试不可关联 |
|
||||
| 进行中计划修改 | [ASSUMPTION] IN_PROGRESS 状态下，不允许修改培训对象和时间范围 | 400：培训进行中，不可修改 |
|
||||
| 知识引用保护 | 已关联计划的知识被下架时触发警告 | knowledge 模块负责，见知识库模块 6 |
|
||||
| 学员查看非自己的计划 | Service 层校验该学员是否在 tr_plan_target 覆盖范围内 | 403：无权访问该培训计划 |
|
||||
|
||||
### 3.3 状态流转
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> NOT_STARTED : 创建培训计划（start_date 未到）
|
||||
NOT_STARTED --> IN_PROGRESS : start_date 到达（自动/定时）
|
||||
IN_PROGRESS --> ENDED : end_date 到达（自动/定时）
|
||||
NOT_STARTED --> [*] : 逻辑删除（未开始可删除）
|
||||
ENDED --> [*] : 归档
|
||||
|
||||
note right of IN_PROGRESS : 学员可学习和考试
|
||||
note right of ENDED : 仅供历史查阅
|
||||
```
|
||||
|
||||
**学员培训进度状态（非独立表字段，实时计算）**：
|
||||
- 0%：尚未开始学习
|
||||
- 1%~99%：学习中
|
||||
- 100%：全部必修项完成（培训通过）
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据结构
|
||||
|
||||
[SRC-SQL-01：四、培训模块]
|
||||
|
||||
### 4.1 涉及数据表
|
||||
|
||||
**tr_plan**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| title | VARCHAR(200) NOT NULL | 计划标题 |
|
||||
| description | TEXT | 计划描述 |
|
||||
| start_date | DATE NOT NULL | 开始日期 |
|
||||
| end_date | DATE NOT NULL | 结束日期 |
|
||||
| department_id | BIGINT NOT NULL | 所属部门（数据隔离键） |
|
||||
| status | TINYINT | 0-未开始 / 1-进行中 / 2-已结束 |
|
||||
| creator_id | BIGINT NOT NULL | 创建人 |
|
||||
|
||||
**tr_plan_knowledge**（培训计划-知识关联）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| plan_id | BIGINT NOT NULL | 培训计划 ID |
|
||||
| knowledge_id | BIGINT NOT NULL | 知识 ID |
|
||||
| required | TINYINT DEFAULT 1 | 1-必修 / 0-选修 |
|
||||
| sort_order | INT | 排序 |
|
||||
|
||||
**tr_plan_exam**（培训计划-考试关联，V1.0.1）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| plan_id | BIGINT NOT NULL | 培训计划 ID |
|
||||
| exam_id | BIGINT NOT NULL | 考试 ID |
|
||||
| required | TINYINT DEFAULT 1 | 1-必考 / 0-选考 |
|
||||
| sort_order | INT | 排序 |
|
||||
| 唯一约束 | uk_plan_exam | (plan_id, exam_id) |
|
||||
|
||||
**tr_plan_target**（培训计划-分配对象）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| plan_id | BIGINT NOT NULL | 培训计划 ID |
|
||||
| target_type | TINYINT NOT NULL | 0-部门 / 1-小组 / 2-个人 |
|
||||
| target_id | BIGINT NOT NULL | 对应实体 ID |
|
||||
|
||||
**tr_plan_progress**（知识级别进度，供快速查询）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| plan_id | BIGINT NOT NULL | 培训计划 ID |
|
||||
| user_id | BIGINT NOT NULL | 学员 ID |
|
||||
| knowledge_id | BIGINT NOT NULL | 知识 ID |
|
||||
| completed | TINYINT DEFAULT 0 | 0-未完成 / 1-已完成 |
|
||||
| complete_time | DATETIME | 完成时间 |
|
||||
|
||||
### 4.2 数据关联
|
||||
|
||||
- `tr_plan_knowledge.plan_id` → `tr_plan.id`
|
||||
- `tr_plan_knowledge.knowledge_id` → `km_knowledge.id`
|
||||
- `tr_plan_exam.plan_id` → `tr_plan.id`
|
||||
- `tr_plan_exam.exam_id` → `ex_exam.id`
|
||||
- `tr_plan_target` 多态关联：type=0→`sys_department.id`；type=1→`sys_group.id`；type=2→`sys_user.id`
|
||||
- 进度计算同时读取 `km_knowledge_progress`（source=TRAINING, plan_id）和 `ex_exam_record`（passed=1）
|
||||
|
||||
---
|
||||
|
||||
## 5. 对外接口
|
||||
|
||||
[SRC-API-01：4.5] [SRC-CODE-01：module/training/controller/]
|
||||
|
||||
| API 名称 | 方法 | 路径 | 权限 |
|
||||
|---------|------|------|------|
|
||||
| 培训计划列表（讲师） | GET | /api/training | LECTURER/ADMIN |
|
||||
| 创建培训计划 | POST | /api/training | LECTURER/ADMIN |
|
||||
| 修改培训计划 | PUT | /api/training/{id} | LECTURER/ADMIN |
|
||||
| 删除培训计划 | DELETE | /api/training/{id} | LECTURER/ADMIN |
|
||||
| 关联知识 | POST | /api/training/{id}/knowledge | LECTURER/ADMIN |
|
||||
| 关联考试 | POST | /api/training/{id}/exam | LECTURER/ADMIN |
|
||||
| 分配对象 | POST | /api/training/{id}/target | LECTURER/ADMIN |
|
||||
| 学员-培训列表 | GET | /api/student/training | STUDENT |
|
||||
| 学员-培训详情 | GET | /api/student/training/{id} | STUDENT |
|
||||
|
||||
---
|
||||
|
||||
## 6. 异常与边界处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| 培训计划结束后学员查看 | 状态=ENDED，页面展示历史进度和成绩，不可继续学习/考试 |
|
||||
| 学员尚未被分配到某计划就访问 | 403：无权访问该培训计划 |
|
||||
| 相关考试时间窗口已过，但培训计划仍进行中 | 考试显示"已结束"，无法参加，该考试通过状态默认为"未通过"（评估影响进度） |
|
||||
| 同一学员多次被添加（部门+个人双重覆盖） | tr_plan_target 可能有重复记录，进度计算时去重（按 user_id 聚合） |
|
||||
| 培训计划关联的知识被删除 | tr_plan_knowledge 记录仍在，显示时标注"知识已下架" [ASSUMPTION] |
|
||||
| 总必修项为 0 的计划 | 进度直接返回 100%（calculateProgress 中已处理：totalRequired=0 return 100）[SRC-API-01：5.4] |
|
||||
Reference in New Issue
Block a user