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？

确凿结论：

系统底座首要执行脚本：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 模式下执行。
定时调度基础设施脚本：RuoYi-Vue/sql/quartz.sql
- 内容：创建 Quartz 调度框架所需的 11 张 QRTZ_* 表结构；
代码生成器自增主键兼容补丁：
- 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 RuoYi-Vue/sql/train/v2/bootstrap/000_seed_baseline_teacher.sql
         (确定性注入 1 条基线教师记录 T001，满足 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 张 V2 核心业务表 + 2 张 DMS 扩展表 + 1 张历史表)

3.1 核心业务表总账 (21 张 `train_*` 表，由 `010_verify.sql` 强制断言)

序号	表名 (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_resource`	`VARCHAR(32)`	002	统一教学资源主表，存放课件、视频、教材电子档等元数据	被 `train_course_resource`、`train_study_duration` 引用
05	`train_course_resource`	`BIGINT (ID)`	002	课程与教学资源关联表 (N:M)，指定课程关联课件与资料	关联 `c_id`、`resource_id`
06	`train_classroom_info`	`BIGINT (ID)`	000 + 003	教学教室信息表，记录教室编号、楼栋、容纳人数与配备	被 `train_lesson` 引用 (教室时段互斥)
07	`train_training_site`	`BIGINT (ID)`	000 + 003	实训演练场地表，记录室内/室外工区、容量与安全规范	被 `train_lesson` 引用 (场地时段互斥)
08	`train_electronic_board`	`BIGINT (ID)`	000 + 003	电子班牌硬件设备信息表，记录设备 MAC、SN、挂接教室与通信时间	关联 `bind_classroom_id`
09	`train_dormitory_info`	`BIGINT (ID)`	000 + 003	宿舍房间主表，记录宿舍楼栋、房号、性别分类、总床位数与在用数	被 `train_accommodation`、`train_external_resource_mapping` 引用
10	`train_class_plan`	`VARCHAR(32)`	000 + 003	培训开班计划主表 (物理表名 `train_class_plan`，非 `train_plan`)，控制班级全生命周期	驱动 `train_plan_course`、`train_enrollment`、`train_score_item`
11	`train_plan_course`	`BIGINT (ID)`	002	班级课程关系表 (N:M)，指定培训班开设课程及授课教师	关联 `plan_id`、`c_id`
12	`train_enrollment`	`BIGINT (ID)`	002	参训人员名册表，定义学员参加班级及参训状态 (待报到/在训/结训)	关联 `plan_id`、`student_id`
13	`train_lesson`	`BIGINT (ID)`	002	课次排课表，记录每次课的具体时段、地点与授课教师 (互斥 CHECK)	关联 `plan_course_id`、`t_id`、场地/教室
14	`train_accommodation`	`BIGINT (ID)`	002	学员住宿分配台账表，记录床位分配、入住/退宿/调房生命周期	关联 `enrollment_id`、`dorm_id`
15	`train_dorm_auth`	`BIGINT (ID)`	004 + 系统 009	门禁卡/密码授权编排状态表，维护门锁下发授权生命周期	关联 `accommodation_id`
16	`train_class_report`	`BIGINT (ID)`	004 重建	现场报到核验记录表，学员到校开班报到凭据流水	关联 `enrollment_id`
17	`train_student_checkin`	`BIGINT (ID)`	004 重建	课堂考勤打卡流水表，记录学员签到、签退与出勤状态	关联 `enrollment_id`、`lesson_id`
18	`train_score_item`	`BIGINT (ID)`	002	成绩考评科目项标准表 (理论/实作/平时)，定义满分与权重	关联 `plan_id`、`plan_course_id`
19	`train_student_score`	`BIGINT (ID)`	002	学员细粒度科目成绩得分表，记录各项考评实得分数	关联 `enrollment_id`、`score_item_id`
20	`train_study_duration`	`BIGINT (ID)`	004 重建	自主学习时长流水表，记录学员研读教学资料的计时时长	关联 `enrollment_id`、`plan_course_id`、`resource_id`
21	`train_student_portrait`	`BIGINT (ID)`	004 重建	学员参训全过程综合评估与画像表，多维画像统计数据	关联 `enrollment_id` (uq_student_portrait_enroll)

3.2 外部集成扩展表 (2 张 `train_*` 表，由系统脚本 008 创建)

序号	表名 (TABLE_NAME)	物理主键类型	来源迁移脚本	表职责说明 (PURPOSE)	核心外键与关键关联 (RELATIONSHIPS)
22	`train_external_resource_mapping`	`BIGINT (ID)`	系统 008	外部资源映射关联表，记录本地宿舍与外部 DMS 空间/锁具的映射关系	关联 `dorm_id` (train_dormitory_info)、`external_resource_id`
23	`train_external_operation`	`BIGINT (ID)`	系统 008	外部异步操作流水表，记录向 DMS 下发密码/撤销的异步 operationId 对账流水	关联 `door_auth_id` (train_dorm_auth)、幂等键 `idempotency_key`

3.3 历史遗留与系统底座数据表说明

类别	表名 (TABLE_NAME)	状态与职责说明
历史下线表	`train_score_info`	历史 Phase 0.5 单表成绩模型。状态为 `LEGACY_DROPPED / NON_RUNTIME`。已由 `009_drop_legacy_score.sql` 彻底删除，并由 `010_verify.sql` 强断言不存在。所有 Controller 与运行时 Mapper 已完成 V2 架构平滑切换，底层直接读写 `train_score_item` 与 `train_student_score`，代码库与运行时已实现 0 引用。
系统底座表	`sys_user`	若依平台核心用户主档表，与 `train_teacher`、`train_student` 通过 `user_id` 建立强外键关联与 RBAC 权限绑定。
平台管理表	`sys_dept`、`sys_role`、`sys_menu`、`sys_dict_type`、`sys_dict_data`、`sys_config`、`sys_oper_log` 等	若依平台底层通用表结构，支持多部门组织架构、角色菜单授权与操作审计。

3.4 数据库备份与恢复命令核验 (Kingbase Backup Command Verification)

环境识别：KingbaseES V009R003C018（默认端口 4321，协议兼容 PostgreSQL 语法但系统字典与扩展类型具备独立实现）。
备份工具核验：
- macOS 本地开发机未安装本地 Kingbase/Postgres 二进制工具 (sys_dump/pg_dump not found)；
- 生产及测试环境（宿主机 192.168.139.218）采用 KingbaseES 官方原生逻辑备份工具 sys_dump；
- 官方标准二进制逻辑归档备份命令： sys_dump -h 192.168.139.218 -p 4321 -U <user> -d <dbname> -F c -b -v -f <backup_file.dmp>
- 官方纯文本 SQL 逻辑导出命令： sys_dump -h 192.168.139.218 -p 4321 -U <user> -d <dbname> -f <backup_file.sql>
- 对应恢复工具为 sys_restore 或 ksql；
- 严禁在未验证客户端直接假设 pg_dump，必须使用 KingbaseES 原生 sys_dump 确保对象权限、OID、Identity 自增列序列元数据完整备份。

17 KiB Raw Blame History Unescape Escape