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

03 - 数据库架构、迁移链与真实 Bootstrap Chain (Database and Tables)

核心原则：当前阶段严格只读，不修改数据库，不清库，不执行数据变更，不创建新库。 本文件严谨定义未来纯净演示库建立的真正可重复引导链 (CLEAN_DATABASE_BOOTSTRAP_CHAIN)。

---

1. 数据库基本信息

• 数据库管理系统 (DBMS)：国产人大金仓分析型/事务型关系数据库 (KingbaseES V009R003C018)
• 数据库兼容模式：database_mode = mysql（兼容 MySQL DDL/DML 方言与自增特性）
• 底层内核兼容版本：server_version = 12.1 (PostgreSQL 12 兼容内核)
• 默认 Schema：public
• 正式综合验收数据库：railwaysystem_integrated_qa_20260916
• 当前共享试用数据库：training
• 未来纯净演示数据库规划：training_demo_clean (详见 CLEAN_DEMO_DATABASE_SPEC.md)

---

2. 数据库真正 Bootstrap Chain 深度审计 (Task 1 结论)

2.1 核心疑问解答与实证剖析

A. 一个完全空的 Kingbase 数据库，必须先执行哪个 Base Schema？

确凿结论：

1. 系统底座首要执行脚本：RuoYi-Vue/sql/ry_20250522.sql
   • 内容：创建若依基础平台核心表（sys_dept、sys_user、sys_post、sys_role、sys_menu、sys_user_role、sys_role_menu、sys_role_dept、sys_user_post、sys_oper_log、sys_dict_type、sys_dict_data、sys_config、sys_logininfor、sys_notice、gen_table、gen_table_column），并插入超级管理员账号 (admin / user_id=1)、组织部门、基础字典数据与基础菜单；
   • 方言依赖：必须在 KingbaseES database_mode=mysql 模式下执行。
2. 定时调度基础设施脚本：RuoYi-Vue/sql/quartz.sql
   • 内容：创建 Quartz 调度框架所需的 11 张 QRTZ_* 表结构；
3. 代码生成器自增主键兼容补丁：
   • RuoYi-Vue/sql/generator/kingbase/002a_gen_table_identity_patch.sql
   • RuoYi-Vue/sql/generator/kingbase/002b_gen_table_column_identity_patch.sql
   • 内容：将 gen_table 与 gen_table_column 主键修正为 GENERATED BY DEFAULT AS IDENTITY，防止导入表元数据时发生主键冲突 (02_kingbase_import_identity_patch)。

B. train/v2 migration 的真正前置 schema 是什么？

确凿结论： RuoYi-Vue/sql/train/v2/ 是一套增量重构与演进迁移脚本，绝非从零建库脚本！ 其各步骤依赖的前置物理表如下：

• 000_preflight.sql：严格断言必须精确存在 Phase 0.5 历史基线的 14 张旧业务表、14 PK、24 FK、7 UNIQUE、6 Identity、9 个触发器，且断言 sys_user 必须恰为 1 行、sys_menu 为 106 行、sys_dept 为 15 行、sys_dict_type 为 44 行、sys_dict_data 为 500 行；
• 001_backup_current_schema.sql：通过 CREATE TABLE bak_v1_* AS SELECT * FROM ... 备份 14 张旧表，直接依赖 14 张 Phase 0.5 旧表已存在；
• 002_create_new_tables.sql：创建 V2 新增的 8 张核心表（train_resource、train_course_resource、train_plan_course、train_enrollment、train_lesson、train_accommodation、train_score_item、train_student_score）；
• 003_alter_master_tables.sql：直接依赖 8 张主数据表已存在并对其执行 ALTER TABLE（train_teacher、train_student、train_course、train_classroom_info、train_training_site、train_electronic_board、train_dormitory_info、train_class_plan）；
• 004_rebuild_business_tables.sql：直接依赖 5 张旧过程表已存在（train_dorm_auth、train_class_report、train_student_checkin、train_study_duration、train_student_portrait），校验其为 0 行后 DROP 并重建；
• 008_migrate_teacher.sql：直接依赖 train_teacher 已存在、具备旧字段（t_department、t_title、create_user）及新扩展字段，且严格断言 SELECT count(*) FROM train_teacher = 1（必须有且仅有 1 行基线数据可供清洗提升）；
• 009_drop_legacy_score.sql：直接依赖 train_score_info 已存在且行数为 0，随后解除约束并 DROP。

👉 前置基线提供源：RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql！ 该文件精确定义了 Phase 0.5 历史基线 14 张表物理 DDL、约束与触发器。在一个全新空数据库中，必须先执行该文件并写入 1 条基线教师占位记录，000~010 迁移链方可成功跑通！

C. system/kingbase 001~015 的前置条件是什么？

确凿结论： RuoYi-Vue/sql/system/kingbase/ 中的补丁同样是增量补丁，其依赖条件如下：

• 001_sys_oper_log_cost_time.sql：依赖 public.sys_oper_log 表存在；
• 002、003、010、011、012、013、014、015：均对 public.sys_menu 及 public.sys_role_menu 执行 INSERT / UPDATE，依赖 sys_menu、sys_role_menu 存在；
• 004_rbac_identity_binding.sql：对 train_teacher 与 train_student 增加 user_id 并创建外键指向 sys_user(user_id)，必须依赖 train_teacher、train_student 与 sys_user 均已存在；
• 005_training_roles_permissions.sql：创建培训角色（role_id=3 train_admin, role_id=4 train_teacher, role_id=5 train_student），依赖 sys_role、sys_menu、sys_role_menu 存在；
• 006_accommodation_history_constraint.sql：在 train_accommodation 上创建局部唯一索引，依赖 train_accommodation 表已存在（由 002_create_new_tables.sql 创建）；
• 008_external_resource_operation.sql：创建 train_external_resource_mapping（外键引用 train_dormitory_info(dorm_id)）与 train_external_operation，依赖 train_dormitory_info 表已存在；
• 009_dorm_authorization_orchestration.sql：修改 train_dorm_auth 表结构并添加指向 train_accommodation(accommodation_id) 的外键，依赖 train_dorm_auth（004 重建后）与 train_accommodation 均已存在；
• 015_dms_package_a_hardening.sql：向 role_id=3 (train_admin) 授权 menu_id=2263 (train:accommodation:edit)，依赖 sys_role (已包含 role_id=3) 与 sys_menu 均已存在；
• (注：007 号脚本因历史规划冲突被跳过，严禁执行 007_dicts.sql)。

---

2.2 严格可重复执行的引导链定义 (CLEAN_DATABASE_BOOTSTRAP_CHAIN)

基于上述源码与 SQL 依赖实证，建立唯一的 7 阶段标准建库流水线：

================================================================================
          CLEAN_DATABASE_BOOTSTRAP_CHAIN (标准纯净库引导执行链)
================================================================================

[STEP 0: 数据库实例与方言就绪]
  └─ 执行: CREATE DATABASE training_demo_clean WITH OWNER = kingbase;
  └─ 确保: database_mode = mysql, search_path = public

[STEP 1: RuoYi 基础平台结构与初始化]
  ├─ 1.1 RuoYi-Vue/sql/ry_20250522.sql (sys_* 基础表与系统管理员、默认字典)
  ├─ 1.2 RuoYi-Vue/sql/quartz.sql (QRTZ_* 调度引擎 11 张基础表)
  └─ 1.3 RuoYi-Vue/sql/generator/kingbase/ (002a + 002b Generator 主键 Identity 补丁)

[STEP 2: 培训业务历史基线骨架构建]
  ├─ 2.1 RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql
  │      (创建 14 张 Phase 0.5 历史基线表、外键、唯一约束与 update_time 触发器函数)
  └─ 2.2 注入 1 条符合基线要求的初始教师记录 (为通过 000 预检与 008 数据平滑清洗)

[STEP 3: 培训业务 V2 结构演进迁移]
  ├─ 3.1  000_preflight.sql (严格只读核验 Phase 0.5 基线与 sys_* 行数)
  ├─ 3.2  000_tx_capability_probe.sql (验证显式事务与 DDL 回滚能力)
  ├─ 3.3  001_backup_current_schema.sql (创建 bak_v1_* 历史结构快照)
  ├─ 3.4  002_create_new_tables.sql (创建 8 张 V2 新表: 排课、选课、住宿台账等)
  ├─ 3.5  003_alter_master_tables.sql (解绑旧外键/触发器，扩展主数据表字段)
  ├─ 3.6  004_rebuild_business_tables.sql (重构 5 张空业务过程表)
  ├─ 3.7  005_constraints.sql (补充 V2 级联完整性与 CHECK 互斥约束)
  ├─ 3.8  006_indexes.sql (创建排课冲突与高频组合性能索引)
  ├─ 3.9  【跳过 007_dicts.sql】(严禁执行)
  ├─ 3.10 008_migrate_teacher.sql (清洗提升 1 条基线教师并固化 NOT NULL 约束)
  ├─ 3.11 009_drop_legacy_score.sql (安全淘汰旧 train_score_info 表)
  └─ 3.12 010_verify.sql (终检验收 V2 架构 100% 合规)

[STEP 4: 系统底层与权限治理强化补丁]
  ├─ 4.1  001_sys_oper_log_cost_time.sql (日志耗时字段)
  ├─ 4.2  002_legacy_analytics_permissions.sql
  ├─ 4.3  003_report_attendance_action_permissions.sql
  ├─ 4.4  004_rbac_identity_binding.sql (强绑定教师/学员与 sys_user 账号)
  ├─ 4.5  005_training_roles_permissions.sql (初始化 train_admin/teacher/student 3大业务角色)
  ├─ 4.6  006_accommodation_history_constraint.sql (在用床位局部唯一索引)
  ├─ 4.7  008_external_resource_operation.sql (创建外部资源映射与操作流水表)
  ├─ 4.8  009_dorm_authorization_orchestration.sql (门禁凭据与授权生命周期扩展)
  ├─ 4.9  010_dms_access_management_permissions.sql
  ├─ 4.10 011_teacher_student_remove_permissions.sql
  ├─ 4.11 012_analytics_v1_permissions.sql
  ├─ 4.12 013_interaction_route_cleanup.sql
  ├─ 4.13 014_dms_access_safety_and_accommodation_permissions.sql
  └─ 4.14 015_dms_package_a_hardening.sql (ACCOM_PERM 闭环，授权 role_id=3 拥有 menu 2263)

[STEP 5: 数据库架构与完整性断言终检]
  ├─ 断言 21 张 train_* 业务表全部存在且 DDL 结构合规
  ├─ 断言 15 张核心 sys_* 表无受损，角色 3 具备 menu 2263 且无破坏性 remove 权限
  └─ 检查 0 孤儿外键、0 冲突索引

[STEP 6: 确定性演示种子数据灌入 (Deterministic Demo Seed)]
  └─ 灌入时序严密、100% 覆盖 UI 界面的高质量确定性演示业务数据 (绝不含历史脏数据)
================================================================================

---

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

当前正式数据库设计包含且仅包含以下 21 张业务表：

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