railwaysystem/docs/issues-v1/04_wave_plan.md

# RailwaySystem Phase 3：开发批次计划 (Wave Plan)

> **规划目标：** 按照依赖关系与业务闭环推进节奏，将 26 个 P0 Issue 分解为 8 个开发批次（Wave 0 ~ Wave 7），实现敏捷迭代、敏捷交付、敏捷验收。

---

## 1. Wave 推进总览表

| 批次 | 阶段主题 | 核心 Issue 清单 | 预估人日 | 前置准入条件 | 核心产出物 |
|:---|:---|:---|:---|:---|:---|
| **Wave 0** | **工程基线与外部准备** | `ISSUE-11-01`, `ISSUE-11-02`, `ISSUE-06-01` | 2.5 人日 | Phase 3 方案审查通过 | 权限常量基线、字典分类方案、Adapter SPI 及 Mock 桩 |
| **Wave 1** | **基础主数据与计划立项** | `ISSUE-01-01`, `ISSUE-01-02`, `ISSUE-01-03`, `ISSUE-01-04`, `ISSUE-01-05`, `ISSUE-02-01` | 6.0 人日 | Wave 0 权限与工程准备就绪 | 教师/学员/课程/教室/场地/宿舍基础档案、培训计划立项与生命周期 |
| **Wave 2** | **计划配课、参训与排课** | `ISSUE-02-02`, `ISSUE-03-01`, `ISSUE-03-02`, `ISSUE-04-01`, `ISSUE-04-02` | 7.0 人日 | Wave 1 主数据与计划完成 | 本期课程引入、参训名单(含Excel导入)、排课并发四维冲突锁、完整课程表 |
| **Wave 3** | **住宿分配、门禁与报到** | `ISSUE-05-01`, `ISSUE-05-02`, `ISSUE-06-02`, `ISSUE-05-03` | 5.5 人日 | Wave 2 参训名单与 Wave 0 SPI 完成 | 批量住宿智能分配防超卖、调房走读、门禁事务外下发与重试、学员报到时限控制 |
| **Wave 4** | **课次打卡考勤与修正** | `ISSUE-07-01`, `ISSUE-07-02` | 3.0 人日 | Wave 2 排课与 Wave 3 报到完成 | 班牌刷脸签到/签退、INV-01 跨班防护、课次考勤花名册、人工修正留痕 |
| **Wave 5** | **成绩科目、台账与学习记录** | `ISSUE-08-01`, `ISSUE-08-02`, `ISSUE-09-01` | 5.0 人日 | Wave 2 配课与参训名单完成 | 成绩项目权重 100% 校验(INV-04)、成绩录入上限(INV-05)与跨班(INV-02)校验、全班成绩台账大表、外部学习记录幂等三态接入(INV-03) |
| **Wave 6** | **综合工作台与成效统计** | `ISSUE-10-01`, `ISSUE-10-02` | 3.0 人日 | Wave 2~Wave 5 业务数据链路通畅 | 培训计划一站式驾驶舱 (PlanWorkbenchVO)、培训成效统计概览 (PlanStatisticsVO) |
| **Wave 7** | **P0 端到端联调与闭环验收** | `ISSUE-12-01` | 2.5 人日 | Wave 0 ~ Wave 6 全部 Issue 完成 | 17 个 P0 核心用例自动化串联测试、业务全生命周期闭环准入测试报告 |

---

## 2. 各 Wave 详尽实施方案

### Wave 0：工程基线与外部准备 (Wave 0 - Baseline & Adapters)
- **目标：** 统一全系统的 RBAC 权限字符定义，梳理业务字典与系统配置归属，建立外部系统 Mock 桩，为后续各业务模块扫清底层支撑障碍。
- **包含 Issue：**
  - `ISSUE-11-01`: RuoYi RBAC 权限体系与按钮授权集成 (Gemini Flash)
  - `ISSUE-11-02`: 培训业务数据字典与参数配置初始化方案 (Gemini Flash)
  - `ISSUE-06-01`: 外部设备适配器 SPI 体系与 Mock 桩实现 (Gemini Flash)
- **可并行 Issue：** 本 Wave 的 3 个 Issue 彼此完全独立，**可 100% 同步并行开发**。
- **进入条件：** Phase 3 文档技术审查完成。
- **退出准则：**
  - 权限字符统一收敛至 `train:*` 前缀；
  - 字典分类方案清晰无歧义，静态字典与业务数据彻底隔离；
  - 3 大外部 SPI 接口及其 Mock 实现类完成并注入 Spring 上下文。

---

### Wave 1：基础主数据与计划立项 (Wave 1 - Master Data & Plan Creation)
- **目标：** 完成教师、学员（含脱敏与加密）、课程库、空间场地、宿舍基础房间维护，并打通培训计划的基本立项与状态生命周期。
- **包含 Issue：**
  - `ISSUE-01-01`: 师资主数据管理能力 (Gemini Flash)
  - `ISSUE-01-02`: 学员主档建档与安全脱敏管理 (Codex)
  - `ISSUE-01-03`: 课程库基础资料管理 (Gemini Flash)
  - `ISSUE-01-04`: 教学空间资源维护（教室与实训场地） (Gemini Flash)
  - `ISSUE-01-05`: 宿舍房间与楼宇基础数据维护 (Gemini Flash)
  - `ISSUE-02-01`: 培训计划全生命周期创建与管理 (Codex)
- **可并行 Issue：** `ISSUE-01-01` ~ `ISSUE-01-05` 5 个主数据任务可完全并行；`ISSUE-02-01` 可同步启动。
- **进入条件：** Wave 0 权限与字典基准确定。
- **退出准则：**
  - 各主数据表单能正常录入与检索；
  - 学员身份证号落库已使用安全散列查重且密文存储，查询列表脱敏，日志无明文；
  - 培训计划能成功创建、编辑和执行结训状态流转。

---

### Wave 2：计划配课、参训与排课 (Wave 2 - Plan Configuration & Scheduling)
- **目标：** 围绕培训计划开展本期选课、学员进班（支持单增与 Excel 批量导入）、课次排课及稳定主资源行级排他锁冲突检测，生成完整课程表。
- **包含 Issue：**
  - `ISSUE-02-02`: 本期培训课程引入与配置 (Gemini Flash)
  - `ISSUE-03-01`: 本期参训名单维护与单条录入 (Codex)
  - `ISSUE-03-02`: 参训人员 Excel 批量导入与防重校验 (Codex)
  - `ISSUE-04-01`: 课次编排与多维度排课并发冲突检测 (Codex)
  - `ISSUE-04-02`: 培训计划完整课程表聚合展示 (Gemini Flash)
- **可并行 Issue：**
  - `ISSUE-02-02` (配课) 与 `ISSUE-03-01` (名单) 可并行推进；
  - `ISSUE-03-02` 在 `ISSUE-03-01` 完成后推进；
  - `ISSUE-04-01` 在 `ISSUE-02-02` 完成后推进；`ISSUE-04-02` 紧随其后。
- **进入条件：** Wave 1 基础主数据与培训计划立项完成。
- **退出准则：**
  - 课程成功引入计划生成 `plan_course_id`；
  - 学员成功入班生成 `enrollment_id`；
  - Excel 批量导入支持容错并反馈错误行；
  - 排课并发压测下杜绝教师/教室/场地/班级重叠穿透，完整课表 VO 正确呈现。

---

### Wave 3：住宿分配、门禁与报到 (Wave 3 - Accommodation, Door Auth & Report)
- **目标：** 解决学员现场报到与在校住宿生活保障，落实宿舍并发预分配防超卖、单人调房、走读退宿、门禁事务外解耦同步与失败重试，以及报到时限告警控制。
- **包含 Issue：**
  - `ISSUE-05-01`: 批量住宿智能预分配与防超卖控制 (Codex)
  - `ISSUE-05-02`: 住宿人工调房、走读设置与住宿安排查看 (Codex)
  - `ISSUE-06-02`: 门禁授权事务后解耦下发与失败手工重试 (Codex)
  - `ISSUE-05-03`: 学员报到确认与生命周期时限控制 (Codex)
- **可并行 Issue：**
  - `ISSUE-05-01` (住宿分配) 与 `ISSUE-05-03` (报到确认) 均依赖名单，两者可完全并行开发；
  - `ISSUE-05-02` 与 `ISSUE-06-02` 在 `ISSUE-05-01` 完成后开展。
- **进入条件：** Wave 2 参训名单已就绪、Wave 0 门禁 Mock 桩就绪。
- **退出准则：**
  - 宿舍分配严格性别隔离，`SELECT FOR UPDATE` 彻底杜绝超卖；
  - 门禁下发失败不回滚住宿事务，支持界面一键重试；
  - 学员报到状态顺利流转，逾期报到准确提示并支持管理员强制放行。

---

### Wave 4：课次打卡考勤与修正 (Wave 4 - Attendance & Rectification)
- **目标：** 支撑教学过程中按课次组织的出勤打卡，落实 INV-01 跨班一致性硬校验，提供考勤名单实时查看与人工修正留痕。
- **包含 Issue：**
  - `ISSUE-07-01`: 课次班牌打卡签到签退与跨班不变量防护 (Codex)
  - `ISSUE-07-02`: 课次考勤名单查看与人工考勤状态修正 (Gemini Flash)
- **可并行 Issue：** `ISSUE-07-02` 依赖 `ISSUE-07-01`，为串行推进。
- **进入条件：** Wave 2 课次排课已完成、Wave 3 学员已完成报到。
- **退出准则：**
  - 班牌签到/签退成功落库；
  - **INV-01 跨班签到拦截测试 100% 阻断**；
  - 人工修改考勤结论必须强制标记 `manual_flag = 1` 留痕。

---

### Wave 5：成绩科目、台账与学习记录 (Wave 5 - Assessment & Ingestion)
- **目标：** 完成本期考核科目与权重配置，支持成绩单条/批量录入，落实 INV-02、INV-04、INV-05，输出动态列成绩台账大表，并提供外部实训自主学习流水的三态幂等接入 (INV-03)。
- **包含 Issue：**
  - `ISSUE-08-01`: 本期成绩考核项与权重配置 (Codex)
  - `ISSUE-08-02`: 学员成绩录入、上限校验与全班成绩台账大表 (Codex)
  - `ISSUE-09-01`: 外部实训系统自主学习流水幂等接入 (Codex)
- **可并行 Issue：**
  - `ISSUE-08-01` (科目配置) 与 `ISSUE-09-01` (学习记录) 可并行开发；
  - `ISSUE-08-02` 在 `ISSUE-08-01` 完成后推进。
- **进入条件：** Wave 2 课程配置与参训名单已就绪。
- **退出准则：**
  - 成绩项目总权重严格校验 100% (INV-04)；
  - 打分录入严格限制在 `[0, fullScore]` 内 (INV-05) 且严禁跨班打分 (INV-02)；
  - 全班台账大表准确输出加权总分 `weightedTotalScore`，无及格线硬阻断；
  - 外部学习记录实现 `accepted / duplicate / invalid` 三态幂等响应与跨班阻断 (INV-03)。

---

### Wave 6：综合工作台与成效统计 (Wave 6 - Workbench & Statistics)
- **目标：** 将前面各业务阶段汇聚沉淀的数据进行跨表只读聚合，输出培训计划综合工作台驾驶舱与全景成效统计概览。
- **包含 Issue：**
  - `ISSUE-10-01`: 培训计划综合工作台聚合服务 (Gemini Flash)
  - `ISSUE-10-02`: 培训计划综合成效统计概览 (Codex)
- **可并行 Issue：** `ISSUE-10-01` 与 `ISSUE-10-02` **可完全并行开发**。
- **进入条件：** 报到、考勤、成绩与学时业务链路皆已走通。
- **退出准则：**
  - 工作台展示开班全景、今日课表与关键待办，响应时间 < 300ms；
  - 统计概览计算报到率、出勤率、加权平均分与学时，安全防护除以零异常。

---

### Wave 7：P0 端到端联调与闭环验收 (Wave 7 - End-to-End Acceptance)
- **目标：** 串联 17 个 P0 核心用例（UC-01 ~ UC-29），构建端到端自动化测试流水线，作为 Phase 3 研发交付的最终质量关卡。
- **包含 Issue：**
  - `ISSUE-12-01`: 智慧培训全生命周期主链路端到端集成测试与验收 (Codex)
- **进入条件：** Wave 0 ~ Wave 6 全部 25 个 Issue 开发完成并通过独立单测。
- **退出准则：**
  - 自动化端到端测试用例 100% 绿灯通过；
  - 5 大跨表硬不变量在链路测试中均通过破坏性用例校验；
  - 生成最终《P0 业务主链路准入验收报告》。