# 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](../../doc/README.md)
* 核心业务主链规范：[02-business-process.md](02-business-process.md)
* API 端点清单：[06-api-and-permission-overview.md](06-api-and-permission-overview.md)
* 自动化测试验证矩阵：[07-testing-and-acceptance.md](07-testing-and-acceptance.md)