# 03 - 数据库架构、迁移链与数据表总账 (Database and Tables)

> **核心原则**：当前阶段**严格只读，不修改数据库，不清库，不执行数据变更**。
> 后续演示重构必须基于本文件定义的迁移链构建纯净演示库：`CLEAN_DEMO_DATABASE`。

---

## 1. 数据库基本信息

- **数据库管理系统 (DBMS)**：国产人大金仓分析型/事务型关系数据库 (KingbaseES V009R003C018)
- **数据库兼容模式**：Oracle / PostgreSQL 双模式兼容方言
- **默认 Schema**：`public`
- **正式综合验收数据库**：`railwaysystem_integrated_qa_20260916`
- **当前共享试用数据库**：`training`
- **DDL 规范要点**：
  - 自增主键使用 `bigint GENERATED BY DEFAULT AS IDENTITY` 或业务主键 `varchar(32)`；
  - 时间类型统一使用 `timestamp`，严禁 MySQL 方言 `DATETIME` 或 `ON UPDATE CURRENT_TIMESTAMP`；
  - 状态与布尔字段统一使用 `smallint` (0/1)；
  - 字符串必须指定明确编码与长度。

---

## 2. 数据库迁移链定义 (Migration Chain)

系统物理表结构由以下按序执行的迁移脚本链严格定义：

### 2.1 培训业务核心表迁移 (`RuoYi-Vue/sql/train/v2/`)
```text
000_preflight.sql               -- 预检：数据库版本、权限与方言支持
000_tx_capability_probe.sql     -- 事务探针：验证显式事务与 DDL 回滚能力
001_backup_current_schema.sql   -- 架构基线备份 (备份原 V1 表定义)
002_create_new_tables.sql       -- 核心创建：创建 V2 新增的 8 张培训业务核心表
003_alter_master_tables.sql     -- 结构变更：对教师、课程、宿舍表扩展字段与约束
004_rebuild_business_tables.sql -- 重建业务表：重建学员、班级、课次等核心关联
005_constraints.sql             -- 完整性约束：外键、CHECK 约束 (单行互斥、分数非负等)
006_indexes.sql                 -- 性能索引：高频查询、排课时段冲突组合索引
007_dicts.sql                   -- 字典数据 (⚠️ 运行中禁止重复执行，仅限全新建库)
008_migrate_teacher.sql         -- 历史数据迁移：清洗并提升历史教师档案
009_drop_legacy_score.sql       -- 清理废弃结构：安全下线旧版无权重成绩表
010_verify.sql                  -- 终检验收：断言表结构、外键与索引 100% 合规
```

### 2.2 系统底座与权限治理补丁 (`RuoYi-Vue/sql/system/kingbase/`)
```text
001_sys_oper_log_cost_time.sql                                  -- 操作日志补充耗时字段
002_legacy_analytics_permissions.sql                            -- 统计分析历史权限调整
003_report_attendance_action_permissions.sql                    -- 现场报到与考勤动作权限
004_rbac_identity_binding.sql                                   -- 教师与学员用户身份强绑定支持
005_training_roles_permissions.sql                              -- 培训业务角色细粒度权限配置
006_accommodation_history_constraint.sql                        -- 住宿历史单在用唯一约束
008_external_resource_operation.sql                             -- 外部系统操作流水表结构
009_dorm_authorization_orchestration.sql                         -- 宿舍门禁编排中间状态表
010_dms_access_management_permissions.sql                       -- DMS 门禁管理端菜单权限
011_teacher_student_remove_permissions.sql                      -- 教师与学员安全删除权限隔离
012_analytics_v1_permissions.sql                                -- 分析大盘新版看板菜单权限
013_interaction_route_cleanup.sql                               -- 交互路由与无效菜单项清理
014_dms_access_safety_and_accommodation_permissions.sql         -- DMS 安全防线与住宿菜单完善
015_dms_package_a_hardening.sql                                 -- DMS Package A 门禁强化脚本
```

---

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

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

---

## 4. 后续纯净演示库重建计划 (`CLEAN_DEMO_DATABASE`)

为彻底消除历史演示留存的脏数据、断言污染与测试垃圾，后续正式 Demo 执行前**严禁直接使用已污染的旧库**，必须按以下规程建立纯净演示数据库：

```text
[CLEAN_DEMO_DATABASE 重建 SOP]
1. 在 KingbaseES 实例新建独立数据库：training_demo_clean
2. 按序执行 2.1 节 000~010 全量业务迁移脚本 (确保 0 errors)
3. 按序执行 2.2 节 001~015 系统与权限增量补丁
4. 执行全新字典与菜单种子导入
5. 灌入经过严格卫生校验的确定性业务种子数据 (Deterministic Demo Seed):
   - 标准教师 5 名、学员 30 名、课程 6 门、教室 4 间、宿舍 8 间
   - 2 期标准培训班（1 期已结训供查历史，1 期正在进行供现场演示）
   - 保证 100% 前端 UI 具有真实有效数据，无孤儿数据，无外键断裂
```