Kingbase Generator Identity 基础设施补丁

1. 补丁目标

解决 RuoYi 代码生成器（Generator）在 KingbaseES 数据库下执行表结构导入（importGenTable）时，因 gen_table.table_id 和 gen_table_column.column_id 缺失自增/Identity 属性，导致 useGeneratedKeys="true" 回填失败并引发主键冲突（Duplicate key violation）的运行时兼容性问题。

2. 补丁范围与安全红线

涉及对象：严格仅限 public.gen_table.table_id 与 public.gen_table_column.column_id。
安全红线：
- 严禁修改 21 张 train_* 业务表；
- 严禁修改 sys_* 系统/权限/字典表；
- 严禁 DROP 表、重建表或清空/截断 Generator 历史元数据；
- 严禁在未做 Precheck 判定前盲目全量执行 Patch。

3. 文件清单

文件名	类型	说明
`001_generator_identity_precheck.sql`	只读探测	检查两列 Identity 配置、现有数据量及全局 Case 场景。
`002a_gen_table_identity_patch.sql`	DDL 补丁	仅为 `gen_table.table_id` 添加 `GENERATED BY DEFAULT AS IDENTITY`。
`002b_gen_table_column_identity_patch.sql`	DDL 补丁	仅为 `gen_table_column.column_id` 添加 `GENERATED BY DEFAULT AS IDENTITY`。
`003_generator_identity_verify.sql`	只读验证	综合校验列属性、Sequence 存在、依赖关系及 Sequence 对齐安全性。

4. 四种 Partial / Full 执行决策矩阵

根据 001_generator_identity_precheck.sql 查询 4 返回的 precheck_scenario_verdict，严格按以下矩阵执行：

场景编号	Precheck 判定结果	执行动作
Scenario A	`CASE_1_BOTH_NEED_PATCH` （两列均缺失 Identity）	1. 执行 `002a_gen_table_identity_patch.sql` 2. 执行 `002b_gen_table_column_identity_patch.sql` 3. 执行 `003_generator_identity_verify.sql`
Scenario B	`CASE_2_BOTH_ALREADY_PATCHED` （两列均已配置 Identity）	严禁执行任何 Patch！直接执行 `003_generator_identity_verify.sql` 复核。
Scenario C	`CASE_3_ONLY_COLUMN_NEEDS_PATCH` （仅 `column_id` 缺失）	严禁执行 002a！ 1. 仅执行 `002b_gen_table_column_identity_patch.sql` 2. 执行 `003_generator_identity_verify.sql`
Scenario D	`CASE_4_ONLY_TABLE_NEEDS_PATCH` （仅 `table_id` 缺失）	严禁执行 002b！ 1. 仅执行 `002a_gen_table_identity_patch.sql` 2. 执行 `003_generator_identity_verify.sql`

5. 数据环境分类与 Sequence 对齐要求

5.1 Case A：Generator 元数据为空（0 rows，全新环境）

001 预检中 env_type 为 EMPTY_METADATA_ENV；
执行 Patch 后，Kingbase 自动生成的 Sequence 从 1 开始分配；
执行 003 核验，Sequence 对齐状态将显示 EMPTY_TABLE_SAFE，可直接投入使用。

5.2 Case B：Generator 元数据已存在（已有历史导入数据）

001 预检中 env_type 为 EXISTING_METADATA_ENV；
核心风险：Kingbase ADD GENERATED BY DEFAULT AS IDENTITY 在已有数据环境下默认从 1 开始分配，不宣称自动对齐已有数据 MAX(id)！
操作要求：
1. 执行对应补丁后，必须立即执行 003_generator_identity_verify.sql；
2. 观察验证输出中的 seq_alignment_status：
  - 若为 SAFE：表明 sequence 位置已超前于现有数据（例如已有试点导入推进了序列），可直接使用；
  - 若为 UNSAFE：表明 sequence 当前位置落后或等于现有主键，绝对禁止直接继续 Generator Import！
3. Sequence 对齐专项步骤（需 DBA 确认并在维护窗口执行）：针对落后的序列，使用 Kingbase 兼容的管理语法调整序列游标：
```
-- 示例：对齐 gen_table sequence
SELECT setval('gen_table_table_id_seq', (SELECT COALESCE(MAX(table_id), 0) + 1 FROM gen_table), false);
-- 示例：对齐 gen_table_column sequence
SELECT setval('gen_table_column_column_id_seq', (SELECT COALESCE(MAX(column_id), 0) + 1 FROM gen_table_column), false);
```
4. 重新执行 003_generator_identity_verify.sql，确认全部输出 SAFE 且最终结果为 VERIFY: PASS 后，方可开放表导入功能。

6. 执行命令示例（无真实凭据）

# 步骤 1: 预检并确认 Scenario
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 001_generator_identity_precheck.sql

# 步骤 2: 根据 Precheck 决策矩阵有选择地执行对应补丁
# 仅当命中 Scenario A 或 D 时:
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 002a_gen_table_identity_patch.sql
# 仅当命中 Scenario A 或 C 时:
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 002b_gen_table_column_identity_patch.sql

# 步骤 3: 严格复核验证
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 003_generator_identity_verify.sql

4.8 KiB Raw Blame History Unescape Escape