# 04. RailwaySystem 数据模型总览

> **文档定位**：面向技术人员与数据管理者的领域数据模型概览，重点梳理 10 大核心业务实体及其关联关系。
> **当前基线**：Final Candidate `5a49b2e2988bf23ca2a70568264c05b24dfda1b6` (`origin/feat/cicd-pipeline`)

---

## 1. 核心实体领域关系拓扑

系统底层数据模型围绕“**开班计划**”为核心驱动中枢，建立了学员、课程、师资与空间资源的网状关联模型：

```mermaid
graph TD
    Plan["开班计划 (train_class_plan)<br/>主键: plan_id (UUID 32位)"]
    Course["标准课程库 (train_course)<br/>主键: c_id (自增序列)"]
    PlanCourse["本期课程绑定 (train_plan_course)<br/>主键: plan_course_id (自增序列)"]
    Student["学员主档 (train_student)<br/>主键: s_id (UUID 32位)"]
    Enrollment["参训档案 (train_enrollment)<br/>主键: enrollment_id (自增序列)"]
    Lesson["排课课次 (train_lesson)<br/>主键: lesson_id (自增序列)"]
    Classroom["理论教室 (train_classroom_info)<br/>主键: class_room_id (UUID 32位)"]
    Site["实训场地 (train_training_site)<br/>主键: site_id (UUID 32位)"]
    Board["电子班牌 (train_electronic_board)<br/>主键: board_id (UUID 32位)"]
    Report["现场报到流水 (train_class_report)<br/>主键: report_id (自增序列)"]
    Checkin["课次考勤打卡 (train_student_checkin)<br/>主键: checkin_id (自增序列)"]

    Plan -->|1:N 课程绑定| PlanCourse
    Course -->|1:N 课程实例| PlanCourse
    Plan -->|1:N 班级档案| Enrollment
    Student -->|1:N 参训履历| Enrollment
    PlanCourse -->|1:N 安排课次| Lesson
    Plan -->|1:N 课表从属| Lesson

    Enrollment -->|1:N 核验流水| Report
    Enrollment -->|1:N 课堂考勤| Checkin
    Lesson -->|1:N 考勤记录| Checkin

    Classroom -.->|XOR 互斥场地| Lesson
    Site -.->|XOR 互斥场地| Lesson
    Classroom -->|1:N 设备绑定| Board
```

---

## 2. 十大核心业务实体职责说明

| 核心实体表名 | 对应领域概念 | 核心业务主键 | 核心职责与外键关联 |
| :--- | :--- | :--- | :--- |
| **`train_class_plan`** | 开班计划 | `plan_id` (UUID 32位) | 承载培训班全生命周期（名称、起止日期、计划状态、报到截止时间、核定人数）。 |
| **`train_course`** | 标准课程库 | `c_id` (自增序列) | 培训课程标准资产库（课程编码、课程名、建议课时、状态）。 |
| **`train_plan_course`** | 本期课程绑定 | `plan_course_id` (自增序列) | 记录特定开班计划选用的课程，外键关联 `plan_id` 与 `c_id`，并绑定授课教师 `t_id`。 |
| **`train_student`** | 学员主数据档案 | `s_id` (UUID 32位) | 学员基础档案，含脱敏姓名、散列与加密存储的身份证号、联系电话及单位名称。 |
| **`train_enrollment`** | 参训履历档案 | `enrollment_id` (自增序列) | 记录学员参与特定培训班的报名档案，外键关联 `plan_id` 与 `student_id`，维护参训状态。 |
| **`train_lesson`** | 具体课次安排 | `lesson_id` (自增序列) | 记录排课课次，外键关联 `plan_id`、`plan_course_id`、`t_id` 及场地（教室或实训场地互斥）。 |
| **`train_classroom_info`**| 理论教室 | `class_room_id` (UUID 32位)| 教学空间实体，定义容纳人数、多媒体配置及可用状态。 |
| **`train_training_site`** | 实训演练基地 | `site_id` (UUID 32位) | 室外或专业实操演练基地，外键关联课次，与教室互斥。 |
| **`train_class_report`** | 现场开班报到流水 | `report_id` (自增序列) | 记录学员现场报到核验事件，外键关联 `enrollment_id`，记录核验方式与时间。 |
| **`train_student_checkin`**| 课次考勤打卡记录 | `checkin_id` (自增序列) | 唯一约束 `UNIQUE(enrollment_id, lesson_id)`，记录打卡时间、考勤状态及人工修正标志。 |
| **`train_electronic_board`**| 电子班牌物联终端 | `board_id` (UUID 32位) | 外键关联 `class_room_id`，记录设备序列号 `board_sn`、IP 地址及通信端点。 |

---

## 3. 关键物理约束与完整性保证

1. **唯一性约束防重叠**：
   - 同一培训班内同一学员只能有一条有效档案：`uq_train_enrollment(plan_id, student_id)`。
   - 同一学员在同一课次只能产生一条考勤结论：`uq_train_student_checkin(enrollment_id, lesson_id)`。
   - 电子班牌硬件序列号全局唯一：`uq_train_electronic_board_sn(board_sn)`。
2. **空间场地 XOR 互斥**：
   - 课次表（`train_lesson`）中通过数据库检查约束 `chk_lesson_venue` 强制保证理论教室 `class_room_id` 与实训场地 `site_id` 必须二选一填报，杜绝孤立课次或双重占用。
3. **时间逻辑有效性约束**：
   - 课次起止时间强制满足 `lesson_end_time > lesson_start_time`。

---

## 4. 全量物理表事实源链接

关于系统全部 21 张物理表的完整字段清单、数据类型、索引策略与外键级联定义，请直接查阅冻结事实源：
* 📚 **[docs/database-v2/01_table_inventory.md](../database-v2/01_table_inventory.md)**（21 张物理表全景字段字典）
* 📑 **[docs/database-v2/03_constraint_index_review.md](../database-v2/03_constraint_index_review.md)**（数据库约束与索引优化审查）