railwaysystem/docs/database-v2/00_readme.md

# RailwaySystem 数据库 V2 DDL 生成与设计审查概览 (Round 2 最终静态收尾版)

> **设计状态**：数据库 V2 物理 DDL 最终静态收尾就绪（已完成 Round 2 全部 7 项缺陷修复，达到“允许进入测试迁移”标准）
> **最高依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md)
> **业务背景参考**：[`一期 PRD V1.0`](../requirements/一期PRD-V1.0.md)
> **技术基线**：`main@4b450f46`，KingbaseES V009R003C018 (`database=training`, `schema=public`, `database_mode=mysql`)
> **操作定位**：**纯静态收尾与审查阶段**（严禁执行 SQL、严禁修改真实库、严禁改动业务代码、严禁自动 git commit）。

---

## 1. 阶段目标与执行边界

本阶段严格依据技术负责人 Final Static Review 指示，修复 DDL 中剩余的 7 个问题（R2-01 ~ R2-07），使数据库 V2 DDL 达到“允许进入测试迁移”的标准。

### 核心执行边界
- [x] **21 张核心业务表模型冻结**：8 新增 + 13 保留/重构 + 淘汰 `train_score_info` + 严禁 `train_dorm_bed`；
- [x] **删除业务选择型默认值**：核验结果、考勤方式、场地类型、住宿需求、来源类型等必须由应用层明确提供；
- [x] **解耦两个同名 `source_type`**：区分学员主档进入来源与名单进入来源；
- [x] **删除正式迁移对象的 `IF NOT EXISTS`**：避免因已有错误对象导致 DDL 静默跳过；
- [x] **建立 DDL 事务能力探针 (Gate A)**：实证验证实例是否支持 DDL 回滚；
- [x] **骨架校验升级**：Preflight (Gate B) 采用集合比对，Verify 采用定义级深度验收；
- [x] **架构决策冻结**：固化排课/住宿并发控制与跨班一致性 Service 校验边界；
- [x] **绝对零写操作与零代码污染**：未向数据库执行写操作，未修改 Java/Vue 代码，未执行 git commit。

---

## 2. 成果物资产全景清单

### 2.1 物理 SQL 脚本清单 (`RuoYi-Vue/sql/train/v2/`)

| 序号 / 关卡 | 脚本文件 | 事务边界 | 核心职责 |
| :---: | :--- | :---: | :--- |
| **Gate A** | [`000_tx_capability_probe.sql`](../../RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) | 探针显式事务 | **执行前能力探针**：测试 DDL 事务回滚能力，若表残留强行阻断 |
| **Gate B** | [`000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql) | 纯只读骨架断言 | **Phase 0.5 骨架强校验**：集合差集校验 14 PK + 24 FK + 7 UNIQUE + 6 Identity + 9 Triggers |
| **Stage 1** | [`001_backup_current_schema.sql`](../../RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | `BEGIN ... COMMIT` | 备份当前 14 张表数据快照；增加防覆盖强校验，禁止 DROP CASCADE |
| **Stage 2** | [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | `BEGIN ... COMMIT` | 创建 8 张 V2 新表（无 `IF NOT EXISTS`，住宿默认0预分配，无业务默认值） |
| **Stage 3** | [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | `BEGIN ... COMMIT` | 卸载旧触发器与外键，调整 8 张主表（严格 `ADD COLUMN`，加容量 CHECK） |
| **Stage 4** | [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) | `BEGIN ... COMMIT` | 校验 0 行后重构 5 张表（删除 `verify_result`/`checkin_way` 业务默认值） |
| **Stage 5** | [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) | `BEGIN ... COMMIT` | 集中定义 13 组 UNIQUE、26 组 `ON DELETE NO ACTION` 外键与 9 条单行 CHECK |
| **Stage 6** | [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) | `BEGIN ... COMMIT` | 建立外键索引、排课复合冲突索引与双非空过滤的部分唯一索引（无 `IF NOT EXISTS`） |
| **-** | [`007_dicts.sql`](../../RuoYi-Vue/sql/train/v2/007_dicts.sql) | - | 声明 16 组业务字典注册脚本（**本结构迁移阶段跳过不执行**，留待权限阶段） |
| **Stage 7** | [`008_migrate_teacher.sql`](../../RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | `BEGIN ... COMMIT` | 平滑迁移 1 条教师真实数据，校验完整后固化 `status`/`del_flag` 为 NOT NULL 并删除旧列 |
| **Stage 8** | [`009_drop_legacy_score.sql`](../../RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql) | `BEGIN ... COMMIT` | 前置 0 行强阻断校验后，显式解绑旧约束，常规 DROP 淘汰旧表 `train_score_info` |
| **Stage 9** | [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) | 纯只读深度断言 | **“定义级深度验收”** 全量自动化强断言（逐表、列列表、外键删除规则、CHECK定义、默认值） |

### 2.2 应急回滚资产清单 (`RuoYi-Vue/sql/train/v2/rollback/`)

| 序号 | 回滚文件 | 核心职责 |
| :---: | :--- | :--- |
| **0** | [`000_phase05_exact_schema.sql`](../../RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql) | **Phase 0.5 真实物理基线 DDL**（14表字段、PK、24个FK、7组UNIQUE、9个触发器） |
| **1** | [`001_rollback_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/rollback/001_rollback_new_tables.sql) | 显式解除外键依赖，按拓扑反序常规 DROP 8 张 V2 新增表（`BEGIN ... COMMIT`） |
| **2** | [`002_rollback_modified_tables.sql`](../../RuoYi-Vue/sql/train/v2/rollback/002_rollback_modified_tables.sql) | 基于 `000_phase05_exact_schema.sql` 精确结构重建 13 张表，灌回 `bak_v1_*` 数据并核验教师行数 |
| **3** | [`003_restore_legacy_score.sql`](../../RuoYi-Vue/sql/train/v2/rollback/003_restore_legacy_score.sql) | 基于精确 DDL 重建历史 `train_score_info` 表及 3 个外键与唯一约束 |
| **4** | [`README.md`](../../RuoYi-Vue/sql/train/v2/rollback/README.md) | 应急回滚指南（解耦结构与数据，明确依赖 `000` 结构与 `bak_v1_*` 数据的执行规范） |

### 2.3 架构与设计审查技术文档 (`docs/database-v2/`)

| 序号 | 文档名称 | 主要内容 |
| :---: | :--- | :--- |
| **1** | [`00_readme.md`](00_readme.md) | 本阶段全景综述、规范基线与资产索引导航 |
| **2** | [`01_table_inventory.md`](01_table_inventory.md) | 21 张正式业务表清单、新旧对比、三大核心 ID 落地映射、字段默认值修正 |
| **3** | [`02_migration_plan.md`](02_migration_plan.md) | 迁移执行流水线、双门禁 (Gate A/B) 准入机制、单文件显式事务边界与断点恢复 |
| **4** | [`03_constraint_index_review.md`](03_constraint_index_review.md) | PK、26 组 NO ACTION 外键、13 组 UNIQUE、9 条 CHECK 与复合索引全面审查 |
| **5** | [`04_risk_review.md`](04_risk_review.md) | **R-01 至 R-17** 全景风险深度剖析（固化架构决策 A/B，解耦双 source_type） |
| **6** | [`05_execution_contract.md`](05_execution_contract.md) | **执行契约**（Gate A 事务探针 + Gate B 精确骨架 + 显式事务与即刻熔断） |
| **7** | [`06_review_round1_changes.md`](06_review_round1_changes.md) | **Round 1 修订闭环记录表**（17 项评审意见落实明细） |
| **8** | [`07_review_round2_changes.md`](07_review_round2_changes.md) | **Round 2 修订闭环记录表**（R2-01 ~ R2-07 最终静态收尾明细） |

---

## 3. 人工 Review 准入与优先建议

建议高级技术负责人优先 Review 以下关键文件：
1. **优先审查 Round 2 修订记录表**：[`docs/database-v2/07_review_round2_changes.md`](07_review_round2_changes.md)（核验 R2-01 ~ R2-07 修复明细）；
2. **优先审查执行契约与探针**：[`docs/database-v2/05_execution_contract.md`](05_execution_contract.md) 与 [`RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql`](../../RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql)（核验 Gate A 事务原子性实证机制）；
3. **优先审查 Preflight 骨架校验**：[`RuoYi-Vue/sql/train/v2/000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql)（核验集合比对 14 PK + 24 FK + 7 UNIQUE + 6 Identity + 9 Triggers）；
4. **优先审查 Verify 定义级验收**：[`RuoYi-Vue/sql/train/v2/010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql)（核验定义级断言、CHECK 逻辑与默认值强断言）；
5. **优先审查核心建表与重构脚本**：[`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) 与 [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql)（核验无 `IF NOT EXISTS`、无业务默认值及住宿状态 0）。