0 Fork 0

Files

T

wangzhibiao 82da706006 文档最终交付：完成最终项目文档与Human Portal交付层

2026-09-15 11:59:00 +08:00

11 KiB

Raw Blame History

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

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

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

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

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：

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	请假	针对本堂课次提交了有效公假/病假申请，或由授课教师代签标注为请假。

⚠️ 禁令与口径红线：

严禁出现 attendance_status = 5（已证实为早期文档误将若依字典排序序号 dict_sort=5 当作字典取值）。

严禁使用旧材料中的 4 = 缺勤（当前正式标准中 0 = 缺勤，4 = 请假）。

严禁在报到表中使用旧的 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 四维检测范围

教师时间重叠：同一教师在同一时间段内，严禁在不同培训班同时授课。
理论教室占用：同一间教室在同一时间段内，严禁被两个不同课次同时占用。
实训场地占用：同一个实训演练场地在同一时段内，严禁排入重叠的实操课程。
本班自身课次重叠：同一个培训班内部，课次起止时间不允许自身交叉重叠。

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 开班报到分层与术语规范

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

4.2 课程考勤分层与设备路由

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

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

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

11 KiB Raw Blame History Unescape Escape