174 lines
11 KiB
Markdown
174 lines
11 KiB
Markdown
# 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:待报到 → 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)
|