SQL 版本化规范

在仓库根目录建 sql/，目录树镜像分支树：分支叫什么路径，SQL 就放同路径目录。SQL 在 feature 分支目录中生长（hotfix 分支禁改库，见 03·规则三），最终汇总进 sql/release/<版本>/；打包发版当天冻结为 sql/tag/<版本>/ 最终版（以下为 EasyPro 实际结构，其他产品同理）：

生命周期规则：

1. 创建：规划命名的分支创建时即建同名占位目录；暂无脚本时放一行 README.md 占位锚定目录，写明对应分支与汇总去向。
2. 汇总：feature 的 SQL 合入 release 时按主题归入对应序号文件（同主题追加到已有序号文件末尾，新主题新建下一序号文件）；hotfix 分支不产出 SQL。
3. 序号冲突：并行分支出现同序号不同主题时，后合入者改取下一可用序号。
4. 发版打包：打 tag 当天，把 sql/release/<版本>/ 全量复制为 sql/tag/<版本>/（检查项：该版本的 feature 目录应已全部合入清空）。此后 tag 目录冻结——安装包附带 tag 目录 SQL，现场按序号顺序执行。
5. 发版后：已打包版本的 tag 目录不回改；修正请改 sql/release/<版本>/ 并走下个版本 / hotfix（不改库）/ 维护性微版本流程，通用 DB 修复经回流进入下个开发中版本的汇总。
6. 删除：分支合并删除时，其 SQL 已汇总/回流，对应分支目录一并清理，不在 sql/ 留空壳。
7. 基线：2.1.0 为首个规范化交付版本，目录内含全量建库（ibms-*.sql）+ 增量升级；新现场从 2.1.0 全量起步，老现场按版本逐级升级。

2.1.1 起统一按主题分文件、数字序号定执行顺序：

<序号>_<语义>.sql

• 序号从 0 起，在同一 sql/release/<版本>/ 内递增，数字即执行顺序（CHANGELOG 登记顺序须与之一致）。
• 语义用英文小写 + 下划线，禁止中文、空格；一个驱动/模块一个序号文件（如 0_common.sql、3_modbus.sql）。
• 同一主题的后续变更追加到已有序号文件末尾，不新开文件；新主题才取下一序号。
• 2.1.0 目录的 ibms-*.sql（全量建库）、upgrade_2.1.0*.sql、example.sql 为历史命名，沿用不追溯。

示例：

• 0_common.sql、6_knx.sql
• V2.1.1.1__modbus_write_function_code.sql （V 前缀旧式已弃用，目录名已含版本号）
• 2.1.1增量.sql （中文、无序号）
• update.sql （无序号、无语义）

幂等性要求：每个增量脚本必须可重复执行而不报错、不重复插入。标准做法：

• 列存在性判断：IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE ...)
• 数据存在性判断：游标遍历 + IF NOT EXISTS 插入
• 沿用已验证可靠的「游标遍历 + 幂等保护」成熟范式（现汇总于 sql/release/2.1.1/3_modbus.sql，可直接参考）。

-- 加列前先判断是否已存在
IF NOT EXISTS (
  SELECT 1 FROM information_schema.columns
  WHERE table_name='iot_driver'
    AND column_name='protocol_type'
) THEN
  ALTER TABLE iot_driver
    ADD COLUMN protocol_type VARCHAR(32);
END IF;

-- 直接加，不管列在不在
ALTER TABLE iot_driver
  ADD COLUMN protocol_type VARCHAR(32);

-- 第二遍执行报错：
-- Duplicate column name 'protocol_type'

破坏性变更的安全流程（确需删列/改类型）：

1. 先在新列写入数据（兼容期）。
2. 发版切换读写。
3. 下一版本再删旧列（此时数据已迁移）。
4. 删列脚本必须附 doc/规则/ 备案与回滚脚本。

sql/CHANGELOG.md 作为版本登记表，记录每个脚本的执行情况（唯一权威：顺序、现场登记）：

现场执行流程：

1. 现场拿到新版本安装包后，按 sql/tag/<目标版本>/ 目录下的脚本顺序执行；新现场首次部署先执行 sql/release/2.1.0/ 全量建库；老现场跨版本升级，从自己所处版本之后的 tag 目录起逐版本执行到目标版本。
2. 每执行完一个脚本，在 CHANGELOG.md 对应行的「现场执行」列登记。
3. 执行顺序严格遵循 CHANGELOG 的登记顺序（结构变更优先于依赖它的数据变更）；历史上手工执行过的脚本重复执行无害（幂等），现场登记以首次执行为准。