railwaysystem/docs/handbook/04-data-model-overview.md

04. RailwaySystem 数据模型总览

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

---

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

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

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（21 张物理表全景字段字典）
• 📑 docs/database-v2/03_constraint_index_review.md（数据库约束与索引优化审查）