# RailwaySystem 数据库迁移方案设计 (Migration Plan)

- **设计版本**: R.2A Design Freeze
- **设计日期**: 2026-09-15
- **适用数据库**: 国产主库 KingbaseES V009R003C018 (JDBC 依赖 8.6.0, schema: public)
- **核心目标**: 规范 R.2B 阶段所需的数据库变更脚本清单、序号规则、幂等性保障与零风险回滚方案，确保 100% 兼容现有生产业务。

---

## 1. 现有正式 Migration 脚本全量排查

在设计新脚本前，已完成对代码库中所有既有 SQL 脚本的编号与职责排查：

### 1.1 `RuoYi-Vue/sql/system/kingbase/` (系统级通用补丁)
- `001_sys_oper_log_cost_time.sql`: 操作日志表新增 `cost_time` 耗时列 (BIGINT DEFAULT 0)。
- `002_legacy_analytics_permissions.sql`: 学员画像与学习时长按钮权限补齐。
- `003_report_attendance_action_permissions.sql`: 报到确认与课次考勤核心 Action 权限补齐。
- **最新可用起始编号**: `004`。

### 1.2 `RuoYi-Vue/sql/train/v2/` (培训业务领域专用)
- `000_preflight.sql` ~ `010_verify.sql` (覆盖 V2 架构演进全量表调整与数据过渡)。
- **红线警示**: `007_dicts.sql` 严禁在生产或后续环节执行 (**DO NOT EXECUTE**)。

---

## 2. R.2 计划发布的数据库迁移脚本清单 (PROPOSED_MIGRATIONS)

为避免目录混杂，R.2 的 RBAC 迁移脚本统一归入 `RuoYi-Vue/sql/system/kingbase/` 序列：

```
RuoYi-Vue/sql/system/kingbase/
├── 004_rbac_identity_binding.sql           # 物理约束与身份唯一性索引
└── 005_training_roles_permissions.sql      # 角色预置、菜单补全与权限映射
```

### 2.1 脚本 1: `004_rbac_identity_binding.sql`
- **执行目标**:
  1. 幂等确认 `train_teacher` 和 `train_student` 的 `user_id BIGINT` 列。
  2. 建立针对非空 `user_id` 的部分唯一索引（Partial Unique Index），保障一个登录账户只能绑定一个业务主体。
  3. 增加注释与完整性元数据。
- **DDL 设计核心内容**:
  ```sql
  BEGIN;

  -- 1. 确保列存在 (兼容早期分支)
  ALTER TABLE train_teacher ADD COLUMN IF NOT EXISTS user_id BIGINT;
  ALTER TABLE train_student ADD COLUMN IF NOT EXISTS user_id BIGINT;

  -- 2. 建立教师账号唯一索引 (无 DROP，安全幂等，忽略已删除 del_flag='2' 与空值)
  CREATE UNIQUE INDEX IF NOT EXISTS uq_train_teacher_user_id
  ON train_teacher(user_id)
  WHERE user_id IS NOT NULL AND del_flag = '0';

  -- 3. 建立学员账号唯一索引 (无 DROP，安全幂等)
  CREATE UNIQUE INDEX IF NOT EXISTS uq_train_student_user_id
  ON train_student(user_id)
  WHERE user_id IS NOT NULL AND del_flag = '0';

  COMMENT ON COLUMN train_teacher.user_id IS '关联sys_user.user_id (唯一绑定教师登录账号)';
  COMMENT ON COLUMN train_student.user_id IS '关联sys_user.user_id (唯一绑定学员登录账号)';

  COMMIT;
  ```

### 2.2 脚本 2: `005_training_roles_permissions.sql`
- **执行目标**:
  1. 内置 ID Collision Guard：预检 `role_id (3,4,5)` 与 `menu_id (2201..2240)`，若已被外部其他业务资源占用则显式 ABORT，严禁覆盖外来记录。
  2. 预置 3 个业务角色 (`train_admin`, `train_teacher`, `train_student`) 写入 `sys_role`。
  3. 补齐 `sys_menu` 中历史遗漏的基础模块按钮级权限（`train:teacher:*`, `train:student:*`, `train:course:*`, `train:plan:*`, `train:lesson:*` 等）。
  4. 将 `system:board:*` 权限标识收敛对齐为 `train:board:*`。
  5. 插入 Teacher 工作台菜单与 Student 个人中心菜单节点。
  6. 幂等配置 `sys_role_menu` 角色菜单权限映射。
- **DML 设计核心内容**:
  ```sql
  BEGIN;

  -- 0. ID 碰撞守卫 (Collision Guard)：检测 role_id 与 menu_id 是否有非预期占用，有则 RAISE EXCEPTION
  DO $$ ... $$;

  -- 1. 预置角色 (使用 WHERE NOT EXISTS 确保无重复)
  INSERT INTO sys_role (role_id, role_name, role_key, role_sort, data_scope, menu_check_strictly, dept_check_strictly, status, del_flag, create_by, create_time, remark)
  SELECT 3, '培训管理员', 'train_admin', 3, '1', 1, 1, '0', '0', 'admin', CURRENT_TIMESTAMP, '', NULL, '一期业务全局管理角色'
  WHERE NOT EXISTS (SELECT 1 FROM sys_role WHERE role_id = 3 OR role_key = 'train_admin');

  -- 2. 补齐基础管理模块按钮权限 (示例：教师管理按钮)
  -- 采用 WHERE NOT EXISTS 确保多次执行安全幂等
  -- ... (录入 train:teacher:list/add/edit/query 等节点)

  -- 3. 统一规范电子班牌命名空间
  UPDATE sys_menu SET perms = REPLACE(perms, 'system:board:', 'train:board:') 
  WHERE perms LIKE 'system:board:%';

  -- 4. 建立角色与菜单权限关联 (sys_role_menu)
  -- train_admin: 分配全部培训业务管理菜单及按钮
  -- train_teacher: 分配教师工作台与专属自服务权限
  -- train_student: 分配学员培训中心与专属自服务权限

  COMMIT;
  ```

---

## 3. 生产兼容性与无损回滚设计 (Rollback Safety)

1. **绝对向前兼容 (Zero Breaking Change)**:
   - 现有超级管理员 `admin (role_id=1)` 依靠 `*:*:*` 拥有全量通配权限，新增角色与菜单对已有超管管理流程无任何不良影响。
   - 所有已有历史数据中 `train_teacher.user_id` 和 `train_student.user_id` 为 NULL 的记录完全保留，部分唯一索引不校验 NULL，历史数据不会产生约束冲突。
2. **零 DDL 锁表风险**:
   - KingbaseES / PostgreSQL 架构中，`ADD COLUMN IF NOT EXISTS` 与 `CREATE INDEX ... WHERE ...` 操作毫秒级完成，不锁死数据读写。
3. **独立可执行与验证**:
   - 脚本必须具备单向独立执行性，并在脚本末尾集成 `DO $$ ... RAISE NOTICE ... $$;` 自检核验块。