railwaysystem/docs/current/CLEAN_DEMO_DATABASE_SPEC.md

# 纯净演示数据库设计规约草案 (CLEAN_DEMO_DATABASE_SPEC)

> **文件性质**：设计规约与构建方案草案 (PREFLIGHT SPECIFICATION DRAFT)
> **执行约束**：**本轮禁止创建数据库、禁止 DROP、禁止 TRUNCATE、禁止执行建库 SOP**。

---

## 1. 数据库基本属性定义

| 属性项 | 规划取值 | 依据与说明 |
| :--- | :--- | :--- |
| **数据库标识 (Database Name)** | `training_demo_clean` | 与当前开发库 (`training`) 及验收库 (`railwaysystem_integrated_qa_20260916`) 彻底物理隔离 |
| **数据库管理系统 (DBMS)** | `KingbaseES V009R003C018` | 国产人大金仓数据库，兼容 MySQL 与 PostgreSQL 方言 |
| **方言兼容模式 (Database Mode)**| `mysql` | 兼容若依平台自增主键、数据类型与系统函数 |
| **默认命名空间 (Schema)** | `public` | 严格在 public schema 下构建，防止 search_path 歧义 |
| **数据库属主 (Owner)** | `kingbase` | 拥有完整 DDL/DML 权限 |
| **字符集与排序规则** | `UTF8` / `zh_CN.utf8` | 保证中文字符与国密密文存储无乱码 |

---

## 2. 基础结构源与迁移引导链 (Bootstrap Chain)

纯净库构建必须按以下严格经过验证的顺序执行：

### 2.1 基础平台结构源 (Base Schema Source)
1. **`RuoYi-Vue/sql/ry_20250522.sql`**：
   - 创建若依基础平台表结构并初始化系统管理账号；
2. **`RuoYi-Vue/sql/quartz.sql`**：
   - 创建 Quartz 任务调度表结构；
3. **`RuoYi-Vue/sql/generator/kingbase/`**：
   - 执行 `002a_gen_table_identity_patch.sql` 与 `002b_gen_table_column_identity_patch.sql`，修正 Identity 自增列。

### 2.2 培训历史基线骨架构建 (Phase 0.5 Baseline)
1. **`RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql`**：
   - 创建 14 张 Phase 0.5 历史基线表、外键、局部唯一约束与触发器函数；
2. **确定性基线数据脚本 (Deterministic Baseline Seed Script)**：
   - 执行 `RuoYi-Vue/sql/train/v2/bootstrap/000_seed_baseline_teacher.sql`，以版本控制的确定性 SQL 脚本植入 1 条脱敏基线教师占位记录 (`t_id='T001'`)，确保 `000_preflight.sql` (严格断言 count=1) 与 `008_migrate_teacher.sql` 平滑跑通。

### 2.3 业务 V2 演进迁移链 (Train V2 Migration Chain)
按序执行 `RuoYi-Vue/sql/train/v2/` 目录下脚本：
- `000_preflight.sql` → `000_tx_capability_probe.sql` → `001_backup_current_schema.sql` → `002_create_new_tables.sql` → `003_alter_master_tables.sql` → `004_rebuild_business_tables.sql` → `005_constraints.sql` → `006_indexes.sql` → `008_migrate_teacher.sql` → `009_drop_legacy_score.sql` → `010_verify.sql`。
- *(⚠️ 严禁执行 `007_dicts.sql`)*。

### 2.4 系统与权限治理补丁链 (System Patches 001~015)
按序执行 `RuoYi-Vue/sql/system/kingbase/` 目录下脚本：
- `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` (创建 train_admin, teacher, student 角色)
- `006_accommodation_history_constraint.sql`
- `008_external_resource_operation.sql` (创建外部资源映射与操作流水表)
- `009_dorm_authorization_orchestration.sql`
- `010_dms_access_management_permissions.sql`
- `011_teacher_student_remove_permissions.sql`
- `012_analytics_v1_permissions.sql`
- `013_interaction_route_cleanup.sql`
- `014_dms_access_safety_and_accommodation_permissions.sql`
- `015_dms_package_a_hardening.sql` (授权 train_admin 拥有 menu 2263)

---

## 3. 物理数据表容量预期基准

| 表分类 | 预期表数量 | 表名清单摘要 |
| :--- | :---: | :--- |
| **培训业务核心表 (`train_*`)** | **21 张核心 + 2 张扩展** | 核心 21 表: `train_teacher`, `train_student`, `train_course`, `train_resource`, `train_course_resource`, `train_classroom_info`, `train_training_site`, `train_electronic_board`, `train_dormitory_info`, `train_class_plan`, `train_plan_course`, `train_enrollment`, `train_lesson`, `train_accommodation`, `train_dorm_auth`, `train_class_report`, `train_student_checkin`, `train_score_item`, `train_student_score`, `train_study_duration`, `train_student_portrait`；扩展 2 表: `train_external_resource_mapping`, `train_external_operation` |
| **若依系统底座表 (`sys_*`)** | **15 张** | `sys_user`, `sys_dept`, `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_*`)** | **2 张** | `gen_table`, `gen_table_column` |
| **Quartz 调度表 (`qrtz_*`)** | **11 张** | `qrtz_job_details`, `qrtz_triggers`, `qrtz_simple_triggers`, `qrtz_cron_triggers`, `qrtz_simprop_triggers`, `qrtz_blob_triggers`, `qrtz_calendars`, `qrtz_paused_trigger_grps`, `qrtz_fired_triggers`, `qrtz_scheduler_state`, `qrtz_locks` |
| **历史结构快照备份表 (`bak_v1_*`)**| **14 张** | 由 `001_backup_current_schema.sql` 自动生成，属于备份验证表，不参与业务读写 |

---

## 4. 确定性演示种子数据策略 (Demo Seed Strategy)

### 4.1 目标：`UI_DATA_COVERAGE_TARGET = 100%`
演示数据库必须确保前端 `build_ui/src/views/train/` 下每一个业务视图组件均有丰富、真实、时序合规的业务数据，**0 空白页、0 占位符、0 孤儿外键**。

### 4.2 三层种子数据体系
1. **主数据层 (Master Data)**：
   - 教师档案：5 名资深高铁/房建领域教师，具备完整职称、部门与已绑定的系统登录账号；
   - 课程标准库：6 门理论与实作课程（如《高速铁路路基施工与养护》、《智能门禁系统操作规范》等）；
   - 教学场地：3 间多媒体教室与 2 个专业实训基地；
   - 宿舍资源：2 栋宿舍楼（致远楼、博学楼），共 20 间标准化男女生宿舍。
2. **业务状态数据层 (Business State Data)**：
   - 开班计划：2 期培训班（1 期正在进行中，1 期即将开班）；
   - 班级排课与课表：已排定完备课次日程，无时段冲突，涵盖教室与实训场地；
   - 参训学员名册：每班 15~20 名学员，已完成报到，已生成在训状态；
   - 住宿台账：涵盖“预分配”、“在住”与“已退宿”完整生命周期状态；
   - 考勤与打卡：历史课次具备正常的签到、签退与请假记录；
   - 成绩与档案：历史科目具备考评得分，学员画像视图具备出勤率与能力雷达展示。
3. **交互突变数据层 (Scenario Mutation Data)**：
   - 专为演示现场交互预留的可操作记录：
     - 预留 2 名处于“预分配”状态的学员，供业务人员现场点击“入住”；
     - 预留 2 名处于“在住”状态的学员，供现场点击“调房”与“退宿”；
     - 预留 1 节尚未开始的课次，供现场演示教师“代签”与“补卡”；
     - 预留排课冲突检测用例，展示系统四维冲突拦截能力。

---

## 5. 外部系统与接口策略 (External API & Mock Policy)

1. **Client Real API 策略**：
   - 只读接口（DMS Token、空间查询等）在具备网络条件下接入真实通道；
   - 写操作（密码下发/撤销）在无真实测试门锁前严格禁止发起外网 Mutation。
2. **Mock 标识策略**：
   - 对缺少硬件支撑的模块（如门锁密码生成反馈、电子班牌推送），统一在前端或 Mock 适配层明确标识 `[DEMO MOCK]`，绝不伪造真实硬件回执。
3. **重置策略 (Reset Strategy)**：
   - 编制确定性重置脚本 `reset_demo_data.sql`，执行后可一键将数据库还原为“演示开始前”初始黄金状态，支持反复多次演练。
4. **备份策略 (Backup Strategy)**：
   - 种子数据完全灌入并通过 100% UI 验收后，在 KingbaseES 数据库环境使用官方原生工具 `sys_dump` 执行二进制归档快照导出：
     `sys_dump -h 192.168.139.218 -p 4321 -U <user> -d training_demo_clean -F c -b -v -f training_demo_clean_frozen.dump`
   - 封存 SHA-256 校验和作为确定性基线文件；严禁未经核验在 macOS 开发机或未知环境假定 `pg_dump`。