diff --git a/docs/database-v2/10_stage2_6_structure_validation.md b/docs/database-v2/10_stage2_6_structure_validation.md new file mode 100644 index 000000000..317d03d37 --- /dev/null +++ b/docs/database-v2/10_stage2_6_structure_validation.md @@ -0,0 +1,102 @@ +# RailwaySystem 数据库 V2 Stage 2~6 结构迁移验证报告 + +本文档记录 RailwaySystem 数据库 V2 迁移 **Stage 2 至 Stage 6**(`002_create_new_tables.sql` ~ `006_indexes.sql`)在真实 KingbaseES 数据库环境中的执行与全量元数据核验结果。 + +--- + +## 一、执行环境与基本参数 + +| 配置项 | 参数值 | 状态 | +| :--- | :--- | :--- | +| **执行时间** | 2026-09-14 02:33:41 CST | 全部完成 | +| **数据库版本** | KingbaseES V009R003C018 | 正常 | +| **数据库实例** | `training` | 确认 | +| **当前 Schema** | `public` | 确认 | +| **会话 search_path** | `public, sys_catalog` | 确认 | +| **数据库模式** | `database_mode = mysql` | 确认 | +| **JDBC 驱动** | `com.kingbase8:kingbase8:8.6.0` (preferQueryMode=simple) | 官方原生驱动 | +| **事务控制** | 各阶段独立 `BEGIN ... COMMIT` | 全部完整提交 | + +--- + +## 二、各阶段执行与断言核验矩阵 + +### 2.1 Stage 2: 创建 8 张 V2 新业务表 (`002_create_new_tables.sql`) +- **执行结果**: **PASS** (事务已 COMMIT) +- **新建表清单**: + 1. `train_resource`: 统一教学资源主表 (0 行) + 2. `train_course_resource`: 课程与资源多对多关联表 (0 行) + 3. `train_plan_course`: 培训班与课程关联表 (0 行) + 4. `train_enrollment`: 参训学员登记主表 (0 行) + 5. `train_lesson`: 教学活动排课表 (0 行) + 6. `train_accommodation`: 学员住宿安排表 (0 行) + 7. `train_score_item`: 培训班考核成绩项配置表 (0 行) + 8. `train_student_score`: 学员单项得分明细表 (0 行) +- **核验断言**: 8 张表全部成功创建,行数均为 0;此时数据库中共有 14 (旧) + 8 (新) = **22** 张 `train_*` 表。 + +### 2.2 Stage 3: 改造 8 张主数据表 (`003_alter_master_tables.sql`) +- **执行结果**: **PASS** (事务已 COMMIT) +- **改造要点与断言**: + - `train_class_plan`: 彻底剥离旧单课 `c_id` 与单教师 `t_id` 列,新增 `report_deadline` 报到截止时间与标准审计列。 + - `train_student`: 彻底剥离高校学籍旧列 (`s_department`, `s_major`, `s_class`);新增企业主档与国密治理存储列 (`id_card_ciphertext`, `id_card_hash`, `id_card_last4`, `face_ref`, `source_type`);杜绝任何身份证明文新列。*(注:身份证采用密文 + Hash + last4 的存储模型,具体可逆加密算法后续安全设计阶段冻结)*。 + - `train_dormitory_info`: 彻底剥离旧静态占用列 (`bed_used`, `bed_total`);新增 `dorm_floor`, `capacity`, `gender_type`,建立 `capacity > 0` CHECK 约束。 + - `train_electronic_board`: 彻底解绑旧 `bind_plan_id`,增加 `board_name` (必填且无空串默认) 与 `api_endpoint`。 + - **触发器清理**: 8 个主数据表上的旧 V1 `update_time` 触发器全部成功卸载。 + - **教师数据**: `train_teacher` 仍完整保持 **1** 行过渡态。 + +### 2.3 Stage 4: 重建 5 张业务过程表 (`004_rebuild_business_tables.sql`) +- **执行结果**: **PASS** (事务已 COMMIT) +- **重构要点与断言**: + - `train_dorm_auth`: 核心关联重构为 `accommodation_id` (一对一关联),解耦旧 `student_id`/`plan_id`/`dorm_id`。 + - `train_class_report`: 核心关联重构为 `enrollment_id`,旧预分配列 (`alloc_dorm_id`, `alloc_classroom_id`, `alloc_site_id`) 全部退出。 + - `train_student_checkin`: 核心关联重构为 `enrollment_id`, `lesson_id`, `board_id`,旧 `plan_id`/`c_id`/`student_id`/`lesson_start_time` 全部退出。 + - `train_study_duration`: 引入 `enrollment_id`, `plan_course_id`, `resource_id`, `source_system`, `source_event_id`。 + - `train_student_portrait`: 核心关联重构为 `enrollment_id`。 + +### 2.4 Stage 5: 集中建立约束 (`005_constraints.sql`) +- **执行结果**: **PASS** (事务已 COMMIT) +- **约束元数据核验矩阵**: + - **13 组 V2 唯一约束 (UNIQUE)**: 全部建立且元数据匹配 (覆盖学员身份证Hash、课程编码、班牌SN、宿舍房间、课程资源、班级课程、参训档案、住宿安排、门禁授权、报到记录、课次考勤、考核成绩、综合画像)。 + - **26 组 V2 外键约束 (FK)**: 全部建立且 `delete_rule` 严格为 **`ON DELETE NO ACTION`**,禁止出现 `CASCADE`。 + - **9 组关键业务检查约束 (CHECK)**: + 1. `chk_lesson_time`: `start_time < end_time` + 2. `chk_lesson_venue`: 场地类型 (1:教室, 2:实训场地) 与教室ID/场地ID严格单行互斥 + 3. `chk_score_item_weight`: 成绩单项权重 `0.00 ~ 100.00` + 4. `chk_score_item_full`: 满分设定 `> 0.00` + 5. `chk_student_score_nonneg`: 学员实际得分 `>= 0.00` + 6. `chk_study_seconds`: 有效学习秒数 `>= 0` + 7. `chk_study_time`: 结束时间大于等于开始时间 + 8. `chk_study_source_system`: 外部单号存在时来源系统必须非空 + 9. `chk_dorm_capacity`: 宿舍核定容量 `> 0` + +### 2.5 Stage 6: 创建核心业务与排课索引 (`006_indexes.sql`) +- **执行结果**: **PASS** (事务已 COMMIT) +- **重点索引核验**: + - `idx_lesson_teacher_time`: `ON train_lesson (t_id, start_time, end_time)` + - `idx_lesson_classroom_time`: `ON train_lesson (class_room_id, start_time, end_time)` + - `idx_lesson_site_time`: `ON train_lesson (site_id, start_time, end_time)` + - `uq_idx_study_source_event`: `ON train_study_duration (source_system, source_event_id) WHERE source_system IS NOT NULL AND source_event_id IS NOT NULL` (部分唯一索引建立成功) + - 核心外键及高频检索索引全部建立,当前业务索引总数达到 47 个。 + +--- + +## 三、Stage 6 结束时数据库状态核验 + +| 核验对象 | 状态指标 | 实测值 | 结论 | +| :--- | :--- | :--- | :--- | +| **`train_*` 表总数** | 21 张 V2 正式业务表 + 1 张旧 `train_score_info` | **22** 张 | **PASS** | +| **`bak_v1_*` 备份表总数** | Phase 0.5 历史备份表 | **14** 张 | **PASS** | +| **教师数据** | `train_teacher` | **1** 行 (待 008 迁移) | **PASS** | +| **其他业务数据** | 其余 21 张 `train_*` 表 | 全部 **0** 行 | **PASS** | +| **系统基础表 `sys_user`** | 用户数 | **1** 行 | **PASS** | +| **系统基础表 `sys_menu`** | 菜单数 | **106** 行 | **PASS** | +| **系统基础表 `sys_dept`** | 部门数 | **15** 行 | **PASS** | +| **系统基础表 `sys_dict_type`** | 字典类型数 | **44** 行 | **PASS** | +| **系统基础表 `sys_dict_data`** | 字典数据数 | **500** 行 | **PASS** | + +--- + +## 四、迁移执行边界声明 + +- 截至本报告提交时,**007_dicts.sql、008_migrate_teacher.sql、009_drop_legacy_score.sql、010_verify.sql 均尚未执行**。 +- 数据库结构已完整演进至 Stage 6 阶段,准备进入教师数据迁移阶段 (Stage 7)。