# 02. RailwaySystem 业务全流程与状态机规范

> **文档定位**：详细阐述 RailwaySystem 智慧培训系统一期的业务流转闭环、核心业务规则、状态机生命周期及分层控制机制。
> **当前基线**：Final Candidate `5a49b2e2988bf23ca2a70568264c05b24dfda1b6` (`origin/feat/cicd-pipeline`)

---

## 1. 一期业务全景主链与支线

系统在一期实现中，建立了清晰的“准备阶段 → 编排阶段 → 执行阶段 → 结业归档”业务闭环：

```mermaid
flowchart TD
    subgraph S1["一、资源准备阶段"]
        A["基础主数据录入<br/>(教师档案、学员建档、课程库录入、教室与实训场地、宿舍就绪)"]
    end

    subgraph S2["二、计划与编排阶段"]
        B["创建培训计划 (Plan)<br/>状态: 0:草稿"]
        B1["绑定本期课程 (PlanCourse)<br/>配置教师与学时"]
        B2["录入参训学员 (Enrollment)<br/>状态: 0:待报到"]
        C["发布培训计划 (Plan Publish)<br/>状态流转: 1:进行中"]
        B --> B1
        B --> B2
        B1 --> C
        B2 --> C
    end

    subgraph S3["三、培训执行阶段"]
        D1["开班报到环节 (Report)<br/>人脸/刷卡/扫码核验<br/>状态: 0:待报到 &rarr; 1:已报到"]
        D2["课次排课环节 (Scheduling)<br/>四维时段防重叠预检<br/>(教师/教室/场地/本班)"]
        E["课次考勤环节 (Attendance)<br/>学员打卡 / 教师代签修正 (manual_flag=1)<br/>考勤结论: 0缺勤 / 1正常 / 2迟到 / 3早退 / 4请假"]
        D1 --> E
        D2 --> E
    end

    subgraph S4["四、结训与分析阶段"]
        F["培训结训流转 (Completion)<br/>计划状态: 2:已结束<br/>正常在读学员自动联动: 4:已完成 (退训保护)"]
        G["多维学情分析 (Analytics - Read Only)<br/>报到统计 / 考勤分析 / 学时统计 / 学员画像"]
        F --> G
    end

    A --> B
    C --> D1
    C --> D2
    E --> F
```

### 辅助支线与硬件支撑
* **生活后勤支线 (Accommodation)**：在学员名单录入后至现场报到前，管理员依据参训人员的住宿需求（`accommodationRequired=1`），按照严格性别隔离策略分配宿舍床位，并可触发门禁授权。
* **教学硬件支撑 (Electronic Board)**：电子班牌安装于理论教室或实训场地，作为现场多媒体终端，动态展示教室日程、授课教师、课次信息，并支持学员刷卡/人脸交互。

---

## 2. 核心状态机生命周期规范

### 2.1 参训档案状态机 (`Enrollment Status`)
参训记录（`train_enrollment`）记录学员在特定培训班中的履历状态，其合法值域严格定义为 **0 ~ 4**：

```mermaid
stateDiagram-v2
    [*] --> 待报到 : 名单导入 (0)
    待报到 --> 已报到 : 现场核验通过 (1)
    待报到 --> 请假 : 人工请假 (2)
    待报到 --> 退训 : 退训登记 (3)
    已报到 --> 请假 : 人工请假 (2)
    已报到 --> 退训 : 退训登记 (3)
    已报到 --> 已完成 : 结训批量联动 (4)
    请假 --> 已报到 : 销假复课 (1)
    退训 --> [*] : 永久排除联动
    已完成 --> [*] : 结业归档
```

| 状态码 | 状态名称 | 业务含义 | 触发时机与流转说明 |
| :---: | :--- | :--- | :--- |
| **0** | **待报到** | 学员已被录入开班名单，等待开班现场核验 | 批量导入或手工新增学员入班时的初始状态。 |
| **1** | **已报到** | 学员已到校并在现场核验身份成功 | 执行开班报到动作（人脸/刷卡/二维码/人工）后更新。 |
| **2** | **请假** | 学员因特殊情况无法全程到课或中途请假 | 管理员在参训名单中人工调整学员状态。 |
| **3** | **退训** | 学员因故中途退出本期培训 | 管理员操作退训，该学员将被排除在结训联动更新之外。 |
| **4** | **已完成** | 学员顺利修完本期培训，达到结训要求 | 培训计划结训（`completePlan`）时，系统自动联动批量更新。 |

### 2.2 课次考勤状态机 (`Attendance Status`)
课次考勤记录（`train_student_checkin`）记录学员在具体某节课上的考勤结论，其合法值域严格定义为 **0 ~ 4**：

| 状态码 | 状态名称 | 业务判定标准与规则 |
| :---: | :--- | :--- |
| **0** | **缺勤** | 课次已结束，学员既无打卡流水，亦无请假备案（系统默认或代签缺勤）。 |
| **1** | **正常** | 在规定宽限时间内完成签到，并在课次结束后准时完成签退。 |
| **2** | **迟到** | 签到时间晚于课次开始时间与系统设定的宽限期。 |
| **3** | **早退** | 签退时间早于课次法定结束时间。 |
| **4** | **请假** | 针对本堂课次提交了有效公假/病假申请，或由授课教师代签标注为请假。 |

> ⚠️ **禁令与口径红线**：
> 1. 严禁出现 `attendance_status = 5`（已证实为早期文档误将若依字典排序序号 `dict_sort=5` 当作字典取值）。
> 2. 严禁使用旧材料中的 `4 = 缺勤`（当前正式标准中 `0 = 缺勤`，`4 = 请假`）。
> 3. 严禁在报到表中使用旧的 `report_status`（报到状态统一归口至 `train_enrollment.enrollment_status`，报到流水只记录身份核验结果 `verify_result`）。

### 2.3 报到核验方式 (`Report Way`)
现场报到动作记录（`train_class_report`）中支持的核验方式包括：
* `1`：**人脸识别**（通过智能平板/闸机比对学员底库照片）
* `2`：**身份证刷卡**（读取实体二代身份证或员工卡）
* `3`：**二维码核验**（学员手机出示动态身份凭证核销）
* `4`：**人工录入**（由管理员或班主任核验纸质凭证后人工确认）

---

## 3. 排课编排与智能冲突检测机制 (Scheduling)

排课模块在编排具体课次（`train_lesson`）时，引入了实时四维防重叠检测算法，在业务上明确区分为**软警告 (Warning Conflict)** 与 **硬阻断 (Hard Block)**：

### 3.1 四维检测范围
1. **教师时间重叠**：同一教师在同一时间段内，严禁在不同培训班同时授课。
2. **理论教室占用**：同一间教室在同一时间段内，严禁被两个不同课次同时占用。
3. **实训场地占用**：同一个实训演练场地在同一时段内，严禁排入重叠的实操课程。
4. **本班自身课次重叠**：同一个培训班内部，课次起止时间不允许自身交叉重叠。

### 3.2 冲突级别与处理策略
* **软警告冲突 (Warning Conflict)**：
  - 当检测到潜在的时间安排冲突（如跨班共享场地预警或紧凑排期），前端预检接口将返回详细冲突说明与冲突列表。
  - **业务处理原则**：前端向操作员弹出确认对话框：
    - 若用户点击“取消”：不向服务器发送保存请求，排课操作中止；
    - 若用户核实无误点击“确认继续”：向服务器发送标准的保存请求，正常落库保存。
  - **接口规范**：正式排课接口**禁止任何 `force`、`ignoreConflict` 或 `overrideConflict` 传参**，后端始终执行确定性的安全校验。
  - **浏览器真实交互验收事实**：
    - **Warning Cancel 验证**：触发冲突警告弹窗后点击取消，不产生网络保存，实测 **PASS**；
    - **Warning Confirm/Save 验证**：触发冲突警告弹窗后点击确认继续，标准 POST 成功落库保存，实测 **PASS**；
    - **Lesson Detail GET 调用事实**：排课流程中 `Lesson detail GET: NOT CALLED`（课表采用聚合查询，无需高频单个课次明细往返）。
* **硬阻断规则 (Hard Block - 绝对禁止保存)**：
  - 起止时间非法（如开始时间晚于或等于结束时间）；
  - 培训班计划已锁定或已结训（禁止在已封账计划中变更课次）；
  - 理论教室与实训场地二者均未选，或二者同时被选中（必须严格二选一 XOR 互斥）；
  - 课次绑定的课程不属于当前开班计划（杜绝错链）；
  - 课次已有学员产生出勤打卡流水（杜绝课后篡改排课时间或删除课次）。

---

## 4. 报到与考勤的分层架构设计

在系统实现中，报到与考勤严格遵循“**只读分析查询 (Read-Only Analytics)**”与“**专用业务动作 (Write Actions)**”的分离原则：

### 4.1 开班报到分层与术语规范
1. **术语与界面标签一致性区分**：
   - **UI 菜单标签 (`UI_MENU_LABEL`)**：前端侧边栏菜单当前显示为 **“开班签到”**（位于【统计分析】目录下，对应数据库 `sys_menu.menu_name = '开班签到'`）；
   - **业务术语与契约 (`BUSINESS_TERM`)**：在业务模型、应用服务（`EnrollmentAppService.confirmReport`）与冻结契约中，标准业务术语统一为 **“开班报到 / Report Confirm”**。文档与汇报中保持此明确区分，系统不随意修改 UI 既有菜单。
2. **报到分析与流水查询 (`/train/report`)**：
   - 定位：**只读查询与数据导出 (Read-Only Analytics)**。
   - 展现：开班签到全局列表、按班级检索报到记录、导出 Excel 报表。在真实浏览器验收中验证为 **PASS / Read Only**。
3. **现场报到确认动作 (`confirmReport`)**：
   - 定位：**专用业务操作 (Write Action)**。
   - UI 入口：位于【开班计划管理】页面中，进入具体班级的【参训人员列表 (EnrollmentPanel)】，点击单条学员的【报到】操作按钮。
   - 实测验证：端到端真实调用 `POST /train/enrollments/{enrollmentId}/report`，返回 200 OK，学员状态由 `0:待报到` 成功更新为 `1:已报到`（**PASS**）。

### 4.2 课程考勤分层与设备路由
1. **考勤分析与统计看板 (`/train/checkin`)**：
   - 定位：**只读全局看板与历史数据分析 (Read-Only Analytics)**。
   - 展现：历史打卡明细检索、按学员/课次查询考勤结论、导出出勤报表。浏览器验收实测为 **PASS / Read Only**。
2. **考勤打卡与调整动作 (Attendance Actions)**：
   - 定位：**面向课堂现场与授课教师的专用高安全 Action 接口**。
   - 接口包括：
     - `POST /train/lessons/{lessonId}/attendance/checkin`（学员签到/签退打卡）
     - `POST /train/lessons/{lessonId}/attendance/adjust`（教师代签与请假修正，强制打上 `manual_flag = 1` 审计标记）
   - **界面客观说明**：在当前的桌面后台管理大页面中，考勤以花名册展示为主；现场签到主要面向移动扫码终端、班牌设备接口及教师工作台，当前正式后台大页面并未冗余放置打卡模拟按钮。
3. **电子班牌前端路由事实 (`BOARD_FRONTEND_ROUTE`)**：
   - 在真实浏览器验收中，电子班牌前端页面路由为 **`/equip/board`**（挂载于“教学设施 (equip)”目录下的“电子班牌 (board)”页面，组件为 `train/board`），后端接口路由保持为 `/train/board`。浏览器验收实测为 **PASS**。

---

## 5. 技术参考链接 (Technical References)

* 核心服务与事务边界定义：[docs/api-v2/08_transaction_and_invariants.md](../api-v2/08_transaction_and_invariants.md)
* 核心业务主链集成测试矩阵：[docs/_meta/core-business-test-matrix.md](../_meta/core-business-test-matrix.md)
* 模块指南与用户角色：[05-module-guide.md](05-module-guide.md)
* 质量保障与验收报告：[07-testing-and-acceptance.md](07-testing-and-acceptance.md)