railwaysystem/docs/current/03-DATABASE-AND-TABLES.md

03 - 数据库架构、迁移链与数据表总账 (Database and Tables)

核心原则：当前阶段严格只读，不修改数据库，不清库，不执行数据变更。 后续演示重构必须基于本文件定义的迁移链构建纯净演示库：CLEAN_DEMO_DATABASE。

---

1. 数据库基本信息

• 数据库管理系统 (DBMS)：国产人大金仓分析型/事务型关系数据库 (KingbaseES V009R003C018)
• 数据库兼容模式：Oracle / PostgreSQL 双模式兼容方言
• 默认 Schema：public
• 正式综合验收数据库：railwaysystem_integrated_qa_20260916
• 当前共享试用数据库：training
• DDL 规范要点：
  • 自增主键使用 bigint GENERATED BY DEFAULT AS IDENTITY 或业务主键 varchar(32)；
  • 时间类型统一使用 timestamp，严禁 MySQL 方言 DATETIME 或 ON UPDATE CURRENT_TIMESTAMP；
  • 状态与布尔字段统一使用 smallint (0/1)；
  • 字符串必须指定明确编码与长度。

---

2. 数据库迁移链定义 (Migration Chain)

系统物理表结构由以下按序执行的迁移脚本链严格定义：

2.1 培训业务核心表迁移 (RuoYi-Vue/sql/train/v2/)

000_preflight.sql               -- 预检：数据库版本、权限与方言支持
000_tx_capability_probe.sql     -- 事务探针：验证显式事务与 DDL 回滚能力
001_backup_current_schema.sql   -- 架构基线备份 (备份原 V1 表定义)
002_create_new_tables.sql       -- 核心创建：创建 V2 新增的 8 张培训业务核心表
003_alter_master_tables.sql     -- 结构变更：对教师、课程、宿舍表扩展字段与约束
004_rebuild_business_tables.sql -- 重建业务表：重建学员、班级、课次等核心关联
005_constraints.sql             -- 完整性约束：外键、CHECK 约束 (单行互斥、分数非负等)
006_indexes.sql                 -- 性能索引：高频查询、排课时段冲突组合索引
007_dicts.sql                   -- 字典数据 (⚠️ 运行中禁止重复执行，仅限全新建库)
008_migrate_teacher.sql         -- 历史数据迁移：清洗并提升历史教师档案
009_drop_legacy_score.sql       -- 清理废弃结构：安全下线旧版无权重成绩表
010_verify.sql                  -- 终检验收：断言表结构、外键与索引 100% 合规

2.2 系统底座与权限治理补丁 (RuoYi-Vue/sql/system/kingbase/)

001_sys_oper_log_cost_time.sql                                  -- 操作日志补充耗时字段
002_legacy_analytics_permissions.sql                            -- 统计分析历史权限调整
003_report_attendance_action_permissions.sql                    -- 现场报到与考勤动作权限
004_rbac_identity_binding.sql                                   -- 教师与学员用户身份强绑定支持
005_training_roles_permissions.sql                              -- 培训业务角色细粒度权限配置
006_accommodation_history_constraint.sql                        -- 住宿历史单在用唯一约束
008_external_resource_operation.sql                             -- 外部系统操作流水表结构
009_dorm_authorization_orchestration.sql                         -- 宿舍门禁编排中间状态表
010_dms_access_management_permissions.sql                       -- DMS 门禁管理端菜单权限
011_teacher_student_remove_permissions.sql                      -- 教师与学员安全删除权限隔离
012_analytics_v1_permissions.sql                                -- 分析大盘新版看板菜单权限
013_interaction_route_cleanup.sql                               -- 交互路由与无效菜单项清理
014_dms_access_safety_and_accommodation_permissions.sql         -- DMS 安全防线与住宿菜单完善
015_dms_package_a_hardening.sql                                 -- DMS Package A 门禁强化脚本

---

3. 全量业务数据表总账 (21 张 train_* 表)

表名 (TABLE_NAME)	物理主键类型	表职责说明 (PURPOSE)	核心外键与关键关联 (RELATIONSHIPS)
train_teacher	VARCHAR(32)	授课教师档案主表，记录姓名、工号、职称、身份证（国密密文）	sys_user.user_id (账号绑定关系)
train_student	VARCHAR(32)	参训学员主档表，全周期记录学员信息、单位、手机与国密身份证	sys_user.user_id (账号绑定关系)
train_course	VARCHAR(32)	课程标准库主表，记录课程编号、名称、理论/实作类别与基准学时	被 train_plan_course、train_lesson 引用
train_classroom_info	BIGINT (ID)	教学教室信息表，记录教室编号、楼栋、容纳人数与多媒体配备	被 train_lesson 引用 (教室时段互斥)
train_training_site	BIGINT (ID)	实训演练场地表，记录室外/室内实训工区、容量与安全规范	被 train_lesson 引用 (场地时段互斥)
train_plan	VARCHAR(32)	培训开班计划主表，控制培训项目全生命周期与时间跨度	驱动 train_plan_course、train_enrollment
train_plan_course	BIGINT (ID)	班级课程关系表 (N:M)，指定某培训班开设哪门课及指定授课教师	关联 plan_id、c_id、t_id
train_enrollment	BIGINT (ID)	参训人员名册表，定义哪个学员参加哪期培训班及参训状态	关联 plan_id、s_id (状态: 待报到/在训/结训)
train_lesson	BIGINT (ID)	课次日程排课表，系统排课核心表，记录每次课的具体时段与地点	关联 plan_id、plan_course_id、t_id、教室/场地
train_student_checkin	BIGINT (ID)	课堂考勤打卡流水表，记录学员在课次的签到、签退与出勤状态	关联 lesson_id、s_id (状态: 0缺勤/1正常/2迟到/3早退/4请假)
train_class_report	BIGINT (ID)	现场报到核验记录表，学员到校开班报到凭据流水	关联 enrollment_id、s_id、plan_id
train_dormitory_info	BIGINT (ID)	宿舍房间主表，记录宿舍楼栋、房号、性别分类、总床位数与在用数	被 train_accommodation 引用
train_accommodation	BIGINT (ID)	学员住宿分配台账表，记录床位分配、入住时间、退宿时间与状态	关联 s_id、dorm_id、plan_id (状态: 预分配0/在住1/已退2)
train_score_info	BIGINT (ID)	学员培训成绩表，记录各科目考评得分与最终成绩评定	关联 plan_id、s_id、c_id (score >= 0 CHECK)
train_study_duration	BIGINT (ID)	自主学习时长流水表，记录学员在线研读教学资料的计时时长	关联 s_id、resource_id
train_resource	VARCHAR(32)	统一教学资源主表，存放课件、视频、教材电子档等资源元数据	被 train_course_resource 引用
train_course_resource	BIGINT (ID)	课程与教学资源关联表 (N:M)	关联 c_id、resource_id
train_electronic_board	BIGINT (ID)	电子班牌硬件设备信息表，记录设备 MAC、IP、挂接教室与通信时间	关联 classroom_id
train_external_resource_mapping	BIGINT (ID)	外部资源映射表，记录本地宿舍房间与外部 DMS 空间/锁具的映射	关联 local_resource_id、external_id (DMS)
train_dorm_auth	BIGINT (ID)	门禁卡/密码授权编排状态表，维护门锁下发授权生命周期	关联 accommodation_id、external_auth_id
train_external_operation	BIGINT (ID)	外部异步操作流水表，记录向 DMS 下发密码/撤销的异步 operationId	关联 auth_id、operation_type、重试次数

---

4. 后续纯净演示库重建计划 (CLEAN_DEMO_DATABASE)

为彻底消除历史演示留存的脏数据、断言污染与测试垃圾，后续正式 Demo 执行前严禁直接使用已污染的旧库，必须按以下规程建立纯净演示数据库：

[CLEAN_DEMO_DATABASE 重建 SOP]
1. 在 KingbaseES 实例新建独立数据库：training_demo_clean
2. 按序执行 2.1 节 000~010 全量业务迁移脚本 (确保 0 errors)
3. 按序执行 2.2 节 001~015 系统与权限增量补丁
4. 执行全新字典与菜单种子导入
5. 灌入经过严格卫生校验的确定性业务种子数据 (Deterministic Demo Seed):
   - 标准教师 5 名、学员 30 名、课程 6 门、教室 4 间、宿舍 8 间
   - 2 期标准培训班（1 期已结训供查历史，1 期正在进行供现场演示）
   - 保证 100% 前端 UI 具有真实有效数据，无孤儿数据，无外键断裂