# RailwaySystem Phase 3：Epic 架构概览 (Epic Overview)

> **设计基线：** 紧扣 PRD V1.0 业务闭环与 API Contract V1.0，严禁按 21 张数据库表机械建 Epic。
> **Epic 规划原则：** 每一个 Epic 代表一个**高内聚、有明确业务价值、对主链路有明确支撑的业务能力域**。

---

## 1. Epic 汇总视图

系统一期 P0 研发共划分为 **12 个核心 Epic**，覆盖从基础设施、主数据、开班排课、过程执行、效果评估到端到端验收的完整闭环：

```mermaid
flowchart TB
    subgraph CoreBase["支撑基线与基础数据"]
        E11[EPIC-11 权限/字典/系统基线]
        E01[EPIC-01 基础主数据必要集合]
        E06[EPIC-06 门禁与外部设备Mock]
    end

    subgraph PlanCore["开班与排课核心"]
        E02[EPIC-02 培训计划与本期课程]
        E03[EPIC-03 参训人员管理]
        E04[EPIC-04 排课与课表管理]
    end

    subgraph Execution["过程执行支撑"]
        E05[EPIC-05 住宿与报到管理]
        E07[EPIC-07 课次考勤管理]
        E09[EPIC-09 外部学习记录接入]
    end

    subgraph Assessment["效果评估与结训"]
        E08[EPIC-08 成绩项目与成绩台账]
        E10[EPIC-10 计划统计与综合工作台]
    end

    subgraph Acceptance["端到端验收"]
        E12[EPIC-12 P0端到端业务闭环验收]
    end

    E11 --> E01
    E06 --> E05
    E06 --> E07
    E06 --> E09
    E01 --> E02
    E02 --> E03
    E02 --> E04
    E03 --> E05
    E04 --> E07
    E05 --> E07
    E07 --> E08
    E03 --> E09
    E08 --> E10
    E07 --> E10
    E02 --> E10
    E10 --> E12

    style CoreBase fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px
    style PlanCore fill:#e8f5e9,stroke:#4caf50,stroke-width:1px
    style Execution fill:#e1f5fe,stroke:#03a9f4,stroke-width:1px
    style Assessment fill:#fff8e1,stroke:#ffc107,stroke-width:1px
    style Acceptance fill:#fce4ec,stroke:#e91e63,stroke-width:2px
```

---

## 2. Epic 详细定义

### EPIC-01 基础主数据必要集合 (Base Master Data)
- **Epic ID：** `EPIC-01`
- **业务目标：** 为整个智慧培训业务链路提供最小必需的师资、人员、课程、教室、场地和宿舍主数据底座，支撑后续计划选课、排课冲突校验与住宿分配。
- **包含 P0 Issue：**
  - `ISSUE-01-01`: 师资主数据管理能力 (Teacher CRUD)
  - `ISSUE-01-02`: 学员主档建档与安全脱敏管理 (Student Security & Masking)
  - `ISSUE-01-03`: 课程库基础资料管理 (Course Base CRUD)
  - `ISSUE-01-04`: 教学空间资源维护（普通教室与实训场地） (Classroom & Site)
  - `ISSUE-01-05`: 宿舍房间与楼宇基础数据维护 (Dormitory Info & Cascading Options)
- **对应 P0 API：**
  - `GET /train/teacher/list`, `GET /train/teacher/{tId}`, `POST /train/teacher`, `PUT /train/teacher/{tId}`
  - `GET /train/student/list`, `GET /train/student/{sId}`, `POST /train/student`
  - `GET /train/course/list`, `GET /train/course/{cId}`, `POST /train/course`
  - `GET /train/classroom/list`, `GET /train/classroom/{classRoomId}`, `POST /train/classroom`
  - `GET /train/training-site/list`, `GET /train/training-site/{siteId}`, `POST /train/training-site`
  - `GET /train/dormitory/list`, `GET /train/dormitory/{dormId}`, `POST /train/dormitory`, `GET /train/dormitory/options`
- **涉及数据表：** `train_teacher`, `train_student`, `train_course`, `train_classroom`, `train_training_site`, `train_dormitory_info`
- **明确不做什么：** 不做教师资质多版本审批、不做学员主档多机构合并、不做课程版本流转、不做独立教学资源管理与班牌注册管理（属于 P1）。

---

### EPIC-02 培训计划与本期课程 (Plan & Plan-Course)
- **Epic ID：** `EPIC-02`
- **业务目标：** 实现培训班级项目的立项、编辑、周期维护与结训归档，并支撑本期教学课程的选定与课时引入。
- **包含 P0 Issue：**
  - `ISSUE-02-01`: 培训计划全生命周期创建与管理 (Plan Lifecycle)
  - `ISSUE-02-02`: 本期培训课程引入与配置 (Plan-Course Mapping)
- **对应 P0 API：**
  - `GET /train/plans`, `POST /train/plans`, `GET /train/plans/{planId}`, `PUT /train/plans/{planId}`, `POST /train/plans/{planId}/complete`
  - `GET /train/plans/{planId}/courses`, `POST /train/plans/{planId}/courses`
- **涉及数据表：** `train_class_plan`, `train_plan_course`
- **明确不做什么：** 不做多级立项审批流；一期结训不设考核不及格阻断结业的强制卡点（Review Round 1 明确剔除）。

---

### EPIC-03 参训人员管理 (Enrollment Lifecycle)
- **Epic ID：** `EPIC-03`
- **业务目标：** 建立特定培训计划与学员的强业务绑定关系（形成 `enrollment_id`），支持单名录入与 Excel 批量解析导入，提供参训全景档案查询。
- **包含 P0 Issue：**
  - `ISSUE-03-01`: 本期参训名单维护与单条录入 (Enrollment Core & Detail)
  - `ISSUE-03-02`: 参训人员 Excel 批量导入与防重校验 (Batch Enrollment Import)
- **对应 P0 API：**
  - `GET /train/plans/{planId}/enrollments`, `POST /train/plans/{planId}/enrollments`, `GET /train/enrollments/{enrollmentId}`
  - `POST /train/plans/{planId}/enrollments/batch`
- **涉及数据表：** `train_enrollment`, `train_student`
- **明确不做什么：** 不做复杂的退宿连带手续审批（仅做参训状态变更）；批量导入错误行不引入异步消息通知，直接返回同步解析结果列表。

---

### EPIC-04 排课与课表管理 (Scheduling & Timetable)
- **Epic ID：** `EPIC-04`
- **业务目标：** 支撑培训班课程的教学时段排定，实现教师、普通教室、实训场地、班级时段四维冲突检测与数据库行级排他锁保护，聚合生成本班完整课程表。
- **包含 P0 Issue：**
  - `ISSUE-04-01`: 课次编排与多维度排课并发冲突检测 (Lesson Scheduling & Conflict Lock)
  - `ISSUE-04-02`: 培训计划完整课程表聚合展示 (Plan Timetable Aggregation)
- **对应 P0 API：**
  - `POST /train/plans/{planId}/lessons`, `PUT /train/lessons/{lessonId}`, `POST /train/lessons/check-conflict`
  - `GET /train/plans/{planId}/timetable`
- **涉及数据表：** `train_lesson`, `train_plan_course`, `train_teacher`, `train_classroom`, `train_training_site`
- **明确不做什么：** 不做遗传算法自动智能排课；不做复杂的周循环与双周排课规则；教师个人课表属于 P1。

---

### EPIC-05 住宿与报到管理 (Accommodation & Report)
- **Epic ID：** `EPIC-05`
- **业务目标：** 管理学员参训期间的生活保障与入班核验，包含批量智能预分房（严格按性别隔离与行锁防超卖）、单人调房、走读设定，以及学员现场报到与生命周期时限告警控制。
- **包含 P0 Issue：**
  - `ISSUE-05-01`: 批量住宿智能预分配与防超卖控制 (Batch Accommodation Allocation)
  - `ISSUE-05-02`: 住宿人工调房、走读设置与住宿安排查看 (Accommodation Adjustment & Roster)
  - `ISSUE-05-03`: 学员报到确认与生命周期时限控制 (Student Report & Lifecycle Policy)
- **对应 P0 API：**
  - `POST /train/plans/{planId}/accommodations/preallocate`
  - `PUT /train/enrollments/{enrollmentId}/accommodation`, `PUT /train/enrollments/{enrollmentId}/accommodation/day-student`, `GET /train/plans/{planId}/accommodations`
  - `POST /train/enrollments/{enrollmentId}/report`
- **涉及数据表：** `train_accommodation`, `train_report_record`, `train_dormitory_info`, `train_enrollment`
- **明确不做什么：** 不做水电费计量结算；房态实时网格看板属于 P1；报到逾期不做硬阻断数据库约束，采用弹性时限告警策略。

---

### EPIC-06 门禁与外部设备Mock (Device Integration & Mock)
- **Epic ID：** `EPIC-06`
- **业务目标：** 建立防腐适配器体系 (SPI)，提供电子班牌人脸考勤、智能门禁授权、外部 VR/3D 学习记录对接的 Mock 实现与测试桩，并通过事务提交后（`afterCommit`）轻量解耦触发门禁同步，支持失败重试。
- **包含 P0 Issue：**
  - `ISSUE-06-01`: 外部设备适配器 SPI 体系与 Mock 桩实现 (Adapter SPI & Mocks)
  - `ISSUE-06-02`: 门禁授权事务后解耦下发与失败手工重试 (Door Auth After-Commit & Manual Retry)
- **对应 P0 API：**
  - `POST /train/accommodations/{accommodationId}/auth/sync`
- **涉及数据表：** `train_dorm_auth`, `train_accommodation`, `train_student`
- **明确不做什么：** 严禁对接真实厂家硬件私有协议；严禁引入 MQ、Kafka、RabbitMQ、Outbox 等重型中间件；门禁授权下发流水查询属于 P1。

---

### EPIC-07 课次考勤管理 (Lesson Attendance)
- **Epic ID：** `EPIC-07`
- **业务目标：** 围绕具体课次 (`lesson_id`) 与参训档案 (`enrollment_id`) 开展出勤管理，支撑班牌刷脸打卡签到/签退、任课教师实时查看课次考勤明细，以及异常出勤的人工修正与留痕。
- **包含 P0 Issue：**
  - `ISSUE-07-01`: 课次班牌打卡签到签退与跨班不变量防护 (Check-in/Check-out & Invariant INV-01)
  - `ISSUE-07-02`: 课次考勤名单查看与人工考勤状态修正 (Lesson Attendance Roster & Manual Rectification)
- **对应 P0 API：**
  - `POST /train/attendance/sign-in`, `POST /train/attendance/sign-out`
  - `GET /train/lessons/{lessonId}/attendance`, `PUT /train/attendance/{checkinId}`
- **涉及数据表：** `train_attendance_record`, `train_lesson`, `train_enrollment`
- **明确不做什么：** 不做基于 GPS 地理围栏的移动端打卡；人工补录未打卡记录属于 P1；不变量 INV-01（课次所属班级 == 学员参训班级）在此强制阻断。

---

### EPIC-08 成绩项目与成绩台账 (Score Management)
- **Epic ID：** `EPIC-08`
- **业务目标：** 实现培训班成绩考核科目与百分制权重配置，支持教师对单学员或批量录入成绩，强校验满分上限与跨班归属，生成全班加权综合得分台账大表与单人成绩单。
- **包含 P0 Issue：**
  - `ISSUE-08-01`: 本期成绩考核项与权重配置 (Score Items & Weight Config, Invariant INV-04)
  - `ISSUE-08-02`: 学员成绩录入、上限校验与全班成绩台账大表 (Score Entry, Matrix VO, Invariant INV-02 & INV-05)
- **对应 P0 API：**
  - `GET /train/plans/{planId}/score-items`, `POST /train/plans/{planId}/score-items`
  - `POST /train/scores/entry`, `GET /train/plans/{planId}/scores/matrix`, `GET /train/enrollments/{enrollmentId}/scores`
- **涉及数据表：** `train_score_item`, `train_student_score`, `train_enrollment`
- **明确不做什么：** 不做成绩发布审批流程；Excel 批量导入成绩属于 P1；严禁硬编码及格线与不合格阻断（仅计算 `weightedTotalScore`）。

---

### EPIC-09 外部学习记录接入 (External Learning Records)
- **Epic ID：** `EPIC-09`
- **业务目标：** 对接高铁驾驶模拟舱、VR 实训室、3D 拆装等外部专业设备推送的学习学时流水，提供防重复推送的唯一幂等处理与三态响应。
- **包含 P0 Issue：**
  - `ISSUE-09-01`: 外部实训系统自主学习流水幂等接入 (Learning Record Ingestion & Invariant INV-03)
- **对应 P0 API：**
  - `POST /train/study-records/receive`
- **涉及数据表：** `train_study_duration`, `train_enrollment`, `train_plan_course`
- **明确不做什么：** 不对接大文件视频播放断点与心跳上报；自主学习记录分页检索与单人流水详情属于 P1。

---

### EPIC-10 计划统计与综合工作台 (Plan Workbench & Statistics)
- **Epic ID：** `EPIC-10`
- **业务目标：** 为培训管理人员提供开班期间的“一站式计划综合工作台”与结训阶段的“计划综合统计概览”，聚合展示报到率、出勤率、课表进度、成绩分布与自主学时。
- **包含 P0 Issue：**
  - `ISSUE-10-01`: 培训计划综合工作台聚合服务 (Plan Workbench Aggregation)
  - `ISSUE-10-02`: 培训计划综合成效统计概览 (Plan Statistics Aggregation)
- **对应 P0 API：**
  - `GET /train/plans/{planId}/workbench`
  - `GET /train/plans/{planId}/statistics/overview`
- **涉及数据表：** 跨表只读聚合查询（`train_class_plan`, `train_enrollment`, `train_lesson`, `train_attendance_record`, `train_student_score`, `train_study_duration`）
- **明确不做什么：** 不做复杂的多维 OLAP 钻取报表；不引入 Elasticsearch / ClickHouse 等外部大数据分析引擎；多维度成绩下钻图表属于 P2。

---

### EPIC-11 权限字典与系统基线支撑 (RBAC, Dict & System Baseline)
- **Epic ID：** `EPIC-11`
- **业务目标：** 夯实系统运行底座，全面统一以 `train:*` 为前缀的 RBAC 菜单与按钮授权体系，规范化分类梳理 16 组培训业务字典，消除旧系统权限混乱扩散。
- **包含 P0 Issue：**
  - `ISSUE-11-01`: RuoYi RBAC 权限体系与按钮授权集成 (RBAC Migration & Train Permissions)
  - `ISSUE-11-02`: 培训业务数据字典与参数配置初始化方案 (Dictionary & SysConfig Strategy)
- **对应 P0 API：**
  - 支撑全部 53 个 P0 API 的鉴权拦截与前端按钮 `v-hasPermi` 显隐控制。
- **涉及数据表：** `sys_menu`, `sys_role_menu`, `sys_dict_type`, `sys_dict_data`, `sys_config`
- **明确不做什么：** 本轮严禁执行 `007_dicts.sql` 物理入库；不做动态自定义数据权限过滤规则（一期采用基于角色的标准 RBAC）。

---

### EPIC-12 P0端到端业务闭环验收 (End-to-End Acceptance)
- **Epic ID：** `EPIC-12`
- **业务目标：** 串联 17 个 P0 核心用例（UC-01 ~ UC-29），构建完整的端到端自动化测试链路与基线集成回归用例，确保最小业务闭环能够流畅无缝运转。
- **包含 P0 Issue：**
  - `ISSUE-12-01`: 智慧培训全生命周期主链路端到端集成测试与验收 (End-to-End Acceptance Suite)
- **对应 P0 API：**
  - 贯穿覆盖全部 53 个 P0 API 的链路式调用与数据验证。
- **业务价值：** 彻底杜绝“各个单接口测试通过，连起来无法走通完整培训班”的集成陷阱，作为 Phase 3 研发交付的最终质量闸门。