railwaysystem/docs/handbook/05-module-guide.md

05. RailwaySystem 14 大核心业务模块详细指南

文档定位：从人类视角系统化解析系统的 14 大业务功能模块，涵盖模块定位、主要用户、核心能力与业务规则。 当前基线：Final Candidate 5a49b2e2988bf23ca2a70568264c05b24dfda1b6 (origin/feat/cicd-pipeline)

---

1. 基础资源域模块

1.1 Teacher (教师档案管理)

• 业务定位：全校师资人才库与授课教师资质管理中枢。
• 主要用户：教务管理员。
• 主要功能：教师基础档案维护（工号、姓名、职称、联系电话、所属单位、擅长专业领域）。
• 关键规则：教师联系电话（t_phone）全局唯一；已排入课次的教师在授课周期内禁止物理删除。
• 关联模块：为开班课程绑定（PlanCourse）与课次排课（Scheduling）提供师资实体。
• 实测验收状态：IMPLEMENTED / Teacher PASS（浏览器端到端表单录入、手机号重复校验与列表渲染全部通过）。

1.2 Student (学员主数据档案)

• 业务定位：参训职工统一身份与成长履历主数据中心。
• 主要用户：教务管理员、人事培训主管。
• 主要功能：学员建档、信息检索、所属铁路局与站段维护、敏感信息脱敏与哈希存储。
• 关键规则：身份证号执行安全哈希与密文存储，界面与接口脱敏只显后 4 位；停用状态的学员（status=0）禁止编入任何开班计划。
• 关联模块：为参训名单录入（Enrollment）提供学员主档。
• 实测验收状态：IMPLEMENTED / Student PASS（建档正常、末4位脱敏掩码生效、页面与表单校验通过）。

1.3 Course (培训标准课程库)

• 业务定位：铁路标准化教学大纲与课程资产管理。
• 主要用户：教务规划人员。
• 主要功能：课程新建、课程编码维护、标准课时设定、课程状态启用/停用。
• 关键规则：课程编码（c_code）全局唯一；启用状态的课程才允许被开班计划引用。
• 关联模块：为计划课程配置（PlanCourse）提供标准课程源。
• 实测验收状态：IMPLEMENTED / Course PASS。

1.4 Classroom (理论教室管理)

• 业务定位：教学楼宇内的实体理论教室与多媒体研讨室统筹。
• 主要用户：后勤与教务调度员。
• 主要功能：教室编号、标准座位容纳量、安装多媒体设备标注、使用状态流转。
• 关键规则：核定容纳量用于排课时的班级规模预警；每个教室可物理挂接 0 到 N 台电子班牌。
• 关联模块：为排课（Scheduling）提供理论场地，与电子班牌（Board）形成 1:N 映射。
• 实测验收状态：IMPLEMENTED / Classroom PASS（教室增删改查与容量维护通过）。

1.5 Site (实训演练基地)

• 业务定位：机车检修、调度沙盘、铁道信号等室外/特种实操基地。
• 主要用户：实训指导员、教务调度员。
• 主要功能：演练场地登记、实操工位核定、场地状态维护。
• 关键规则：排课时与理论教室互斥二选一，同一时段同一场地禁止两个班级并发占用。
• 关联模块：为排课（Scheduling）提供实操场地资源。
• 实测验收状态：IMPLEMENTED / Site PASS（场地维护与互斥排课约束通过）。

1.6 Dormitory (宿舍房间与门禁)

• 业务定位：学员集中面授期间的生活后勤与宿位资源保障。
• 主要用户：宿舍管理员、教务后勤人员。
• 主要功能：楼宇房间登记、核定床位数、房间性别属性（男寝/女寝/混合）设定、门禁授权同步。
• 关键规则：严格性别隔离（男学员严禁分入女寝，女学员严禁分入男寝）；严禁超额入住。
• 关联模块：与学员参训档案（Enrollment）关联，根据学员住宿需求提供宿位分配支撑。
• 实测验收状态：IMPLEMENTED / Dormitory PASS。

---

2. 教务编排域模块

2.1 Plan (开班计划管理)

• 业务定位：整个培训业务的大脑中枢，驱动培训生命周期的全流程流转。
• 主要用户：培训主管、班主任、教务管理员。
• 主要功能：开班计划拟定、周期设定、报到截止时限配置、发布开班、一键结训流转。
• 关键规则：计划生命周期状态机（0草稿 -> 1进行中 -> 2已结束）；发布后锁定核心信息；结训时强事务批量联动更新学员履历为“已完成”。
• 关联模块：核心枢纽，聚合 PlanCourse、Enrollment、Lesson 等一切教务活动。
• 实测验收状态：IMPLEMENTED / Plan PASS（32位UUID主键生成、初始0:草稿、发布与结训流转正常）。

2.2 PlanCourse (计划本期课程绑定)

• 业务定位：开班计划的具体教学方案，解决一期多门课程与师资配置问题。
• 主要用户：教务管理员。
• 主要功能：向培训班添加课程、指定授课教师、配置本班专属考核要求与学时。
• 关键规则：同一计划内同一课程不允许重复绑定。
• 关联模块：上接 Plan 与 Course，下为 Lesson 排课提供课程教师关联基准。
• 实测验收状态：IMPLEMENTED / PlanCourse PASS（课程绑定、教师关联及学时自动联动通过）。

2.3 Enrollment (参训人员名单管理)

• 业务定位：学员与具体培训班的正式参训契约与学籍管理。
• 主要用户：班主任、教务管理员。
• 主要功能：批量导入学员名单、单条增删、指定住宿需求、维护参训状态。
• 关键规则：同一学员不可重复报名同一班级；招生人数受限于计划容量上限；状态支持 0待报到、1已报到、2请假、3退训、4已完成。
• 关联模块：连接 Student 与 Plan，是开班报到与课次考勤的核心主表。
• 实测验收状态：IMPLEMENTED / Enrollment PASS（名单导入、容量拦截、初始待报到通过）。

2.4 Scheduling (课次编排与冲突检测)

• 业务定位：教务日历化排课引擎，保障教学资源高效有序运转。
• 主要用户：排课调度员、教师。
• 主要功能：编排具体课次（日期、起止时段）、选择教室/场地、时段失焦四维冲突实时预检。
• 关键规则：严格区分 Warning 与 Hard Block；警告级别若用户确认则允许落库保存，接口禁止任何 force/override 参数；起止时间与二选一场地属于硬阻断。
• 关联模块：依赖 PlanCourse、Classroom、Site，为 Attendance 考勤打卡提供课次载体。
• 实测验收状态：IMPLEMENTED / Scheduling PASS
  • Warning Cancel = PASS
  • Warning Confirm/Save = PASS
  • 接口合规：严格禁止且未出现 force / ignoreConflict / overrideConflict 旁路参数
  • 课次详情查询：Lesson detail GET: NOT CALLED（规范约定无需调用）

---

3. 现场执行与硬件支撑模块

3.1 Report (开班报到 / 界面标签: 开班签到)

• 业务定位：学员报到第一现场的身份快速核验与通道管理。
• 主要用户：现场接待员、报到学员。
• 界面与术语区分：前端菜单显示为 “开班签到” (UI_MENU_LABEL = 开班签到)，业务模型与动作定义统一为 “开班报到 / Report Confirm” (BUSINESS_TERM = 开班报到)。
• 主要功能：支持人脸识别、身份证刷卡、二维码与人工核验；记录报到时间与核验结论。
• 关键规则：报到成功强事务联动参训档案流转为“已报到”；分层设计（查询导出与专用报到 Action 解耦）。
• 实测验收状态：IMPLEMENTED / PASS（已在真实浏览器环境验证 POST /train/enrollments/{id}/report 200 OK，状态由待报到流转为已报到）。

3.2 Attendance (课次考勤打卡)

• 业务定位：课堂出勤精细化管理，真实记录每堂课的出勤状况。
• 主要用户：授课教师、参训学员。
• 主要功能：支持签到打卡、签退打卡、任课教师课堂代签与事假修正。
• 关键规则：考勤状态严格规范为 0缺勤、1正常、2迟到、3早退、4请假；教师代签与修正强制标记 manual_flag=1 留痕；已有出勤记录的课次锁定禁止篡改时间。
• 当前状态：IMPLEMENTED / PASS（全局考勤分析为只读模型，专用 Action 契约完备）。

3.3 Board (电子班牌物联终端)

• 业务定位：教室内智能多媒体终端，实现日程轮播与打卡通信。
• 主要用户：教室学员、现场巡考人员。
• 前端正式路由：/equip/board (BOARD_FRONTEND_ROUTE = /equip/board，位于教学设施目录下，后端 API 保持为 /train/board)。
• 主要功能：班牌设备注册、序列号登记、绑定安装教室、心跳与在线状态维护。
• 关键规则：后端自动生成 UUID 标识；设备在线状态由通信更新，禁止人工在表单篡改；逻辑软删除保护。
• 关联模块：外键绑定 Classroom 教室实体。
• 实测验收状态：IMPLEMENTED / PASS（浏览器实际访问 /equip/board 正常加载渲染，增删改查闭环）。

---

4. 学情分析域模块

4.1 Analytics (学情综合分析与画像)

• 业务定位：多维度教务数据沉淀与大数据智能画像中枢。
• 主要用户：培训管理者、教务处领导。
• 包含能力：
  1. 开班报到统计 (Report Analytics)：全局报到记录检索与导出；
  2. 课次考勤分析 (Attendance Checkin Analytics)：出勤明细分析与缺勤统计；
  3. 自主学习时长统计 (Duration Analytics)：综合学时与系统课时完成度累计；
  4. 学员综合能力画像 (Student Portrait)：学员雷达图、技能标签与成长轨迹。
• 当前交付状态客观说明：
  • V2 Read Model 架构：四大只读数据分析模型与前端界面已全部完成（IMPLEMENTED），并通过了权限对齐（002_legacy_analytics_permissions.sql）；
  • 高级跨期多维聚合计分 (Advanced Aggregation)：属于二期深度分析规划（NOT IN CURRENT CORE ACCEPTANCE），核心验收以当前 V2 只读分析与报表导出为准。
• 实测验收状态：
  • 报到统计 (Report Analytics)：PASS / Read Only
  • 考勤分析 (Checkin Analytics)：PASS / Read Only
  • 学时统计 (Duration)：PASS / Read Only
  • 学员画像 (Portrait)：PASS / Read Only
• 系统工具与审计事实：
  • 操作日志 (OperLog)：PASS
  • 系统工具正常可见：表单构建、代码生成、系统接口（Swagger UI 连通）
  • 角色分配机制：RBAC_ROLE_ASSIGNMENT: ENVIRONMENT_CONFIGURATION
  • 验收数据保留策略：Browser acceptance created/changed data: KEEP_FOR_AUDIT（文档阶段严格保留用于审计回溯，不予清理）

---

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

• 业务需求最高基线：业务需求中心与 PRD V1.0
• 核心业务主链规范：02-business-process.md
• API 端点清单：06-api-and-permission-overview.md
• 自动化测试验证矩阵：07-testing-and-acceptance.md