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。