# 培训计划模块（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] |