railwaysystem/docs/database-v2/02_migration_plan.md

RailwaySystem 数据库 V2 迁移执行计划 (Round 1 修订版)

执行基线：KingbaseES V009R003C018 (schema=public)
设计依据：RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md 及 Round 1 审查要求
前置条件：当前正式库中 train_teacher 精确包含 1 行数据，其余 13 张现有表均为 0 行。

---

1. 迁移执行总体流水线 (含 Preflight 与单文件事务)

整个迁移任务划分为 6 个严格阶段，每个主脚本均自包含显式 BEGIN ... COMMIT 事务边界：

flowchart TD
    S0[Stage 0: 000 只读基线预检 Preflight] -->|核验通过| S1[Stage 1: 001 数据快照与结构备份]
    S1 -->|防覆盖校验通过| S2[Stage 2: 物理结构准备]
    subgraph Stage 2: 物理结构准备 (各脚本独立事务)
        S2_1[002_create_new_tables.sql] --> S2_2[003_alter_master_tables.sql]
        S2_2 --> S2_3[004_rebuild_business_tables.sql]
    end
    S2 --> S3[Stage 3: 完整性约束与索引注入]
    subgraph Stage 3: 完整性建立 (各脚本独立事务)
        S3_1[005_constraints.sql] --> S3_2[006_indexes.sql]
    end
    S3 --> S4[Stage 4: 数据平滑迁移与旧表淘汰]
    subgraph Stage 4: 数据平滑处理 (各脚本独立事务)
        S4_1[008_migrate_teacher.sql] --> S4_2[009_drop_legacy_score.sql]
    end
    S4 --> S5[Stage 5: 010 全面自动化强断言验收]
    S5 -->|验收全部 PASS| DONE((迁移阶段成功闭环))
    S5 -.->|任何断言 FAIL| ROLLBACK[触发 rollback 逆向流水线]

---

2. 阶段明细与操作规范

Stage 0: 只读基线预检 Preflight

• 执行脚本：000_preflight.sql
• 目标：纯只读排查当前环境确实精确处于 Phase 0.5 初始状态。
• 核验准则：
  • 14 张旧表全部存在，8 张 V2 新表均不存在；
  • train_teacher 精确为 1 行，其余 13 张旧表精确为 0 行；
  • 旧外键 fk_classplan_course、旧唯一约束及 9 个旧触发器全部完备。
• 阻断控制：任何一项不符合，立即抛出异常中止，拒绝进入未知环境。

Stage 1: 数据快照备份

• 执行脚本：001_backup_current_schema.sql
• 目标：在显式事务中为当前 14 张培训旧表建立物理快照（bak_v1_*）。
• 防覆盖控制：若检测到既有 bak_v1_* 已存在，立即抛出异常强阻断，杜绝二次执行覆盖最初 V1 备份。

Stage 2: 物理结构准备

• 执行脚本：
  1. 002_create_new_tables.sql：新建 8 张 V2 表（t_id 必填，场地互斥 CHECK，分数非负 CHECK）；
  2. 003_alter_master_tables.sql：卸载主数据旧触发器，显式解除旧外键，调整 8 张主数据表结构（移除猜测默认值，加 capacity > 0 CHECK）；
  3. 004_rebuild_business_tables.sql：校验 0 行后，显式解绑旧外键并常规 DROP，按照 enrollment_id / lesson_id 重建 5 张业务表（增加学时时间与单号系统匹配 CHECK）。

Stage 3: 完整性约束与索引注入

• 执行脚本：
  1. 005_constraints.sql：集中为 21 张表建立 13 组 UNIQUE 约束、26 组 ON DELETE NO ACTION 外键与全量单行 CHECK 约束；
  2. 006_indexes.sql：创建外键索引、排课多维复合冲突索引及双非空部分唯一索引。

Stage 4: 数据平滑迁移与旧表淘汰

• 执行脚本：
  1. 008_migrate_teacher.sql：将教师历史数据映射至新列，校验数据完整性后将 status 与 del_flag 固化为 NOT NULL，安全删除旧列；
  2. 009_drop_legacy_score.sql：前置 0 行校验后，显式解除历史约束并安全常规 DROP。

Stage 5: 全面自动化强断言验收

• 执行脚本：010_verify.sql
• 目标：实现“失败即失败”，逐表逐项强断言，出现任何偏差直接抛异常报错。

---

3. 业务字典脚本定位特别说明

007_dicts.sql 在当前数据库结构迁移阶段明确跳过、不执行。
原因：该脚本向 sys_dict_* 系统表写入业务字典数据，属于 API 契约与权限设计范畴。当前阶段保持数据库结构与应用层配置解耦，待后续权限设计阶段统一执行。

---

4. 断点恢复与精确回滚机制

• 单脚本失败自动撤销：由于各脚本包含显式 BEGIN ... COMMIT，单脚本内部任何错误会自动触发事务 ROLLBACK，数据库保持在上一个脚本执行成功的整齐状态；
• 精确全量回滚保障：若需全量还原，严格基于 rollback/000_phase05_exact_schema.sql 的真实物理 DDL 重建结构，结合 bak_v1_* 快照灌回数据，彻底消除 CTAS 丢失结构缺陷。