BUG-0462project-02高待处理database-schema

4 个数据库迁移文件整份只有一行（LF=0）→ PostgreSQL 的 `--` 注释吃掉全部 SQL，迁移静默 no-op 却记为 applied

发现：2026-10-04验证：2026-10-09置信度：85%

症状

迁移执行**无任何 Error/Exception 报错**，`migration_runner.py` 把文件名写入 `_migrations` 记为 applied，但 schema 毫无变化 —— `BEGIN;` / `ALTER TABLE ...;` / `COMMIT;` 全被行注释吞掉。实测 `019_v3_decimal_precision.sql` 字节 6554 / `LF=0`（整份文件一行），且自引入提交 `7e0ab82`（2026-07-18）起即如此。

根因

PostgreSQL 的行注释 `--` **持续到行尾**。这 4 个迁移文件整份没有换行符，因此首个 `--` 之后的全部 SQL 都成了注释。执行器不报错、按文件名登记为 applied —— “执行成功”与“schema 已变更”之间的差距没有任何机制暴露。该缺陷对代码评审、单元测试、SQL 语法检查**全部免疫**（注释是合法语法）。

修复方案

（019，已完成）按原注释描述的意图重建为格式完好的迁移：`BEGIN` + **9 个 `DO $$ ... IF EXISTS (SELECT 1 FROM information_schema.columns WHERE ... numeric_precision = 12) ... END $$;` 幂等守卫**（bk_vouchers 2 列 / bk_voucher_entries 2 列 / bk_ledger_balances 4 列 / bk_douyin_orders 1 列）+ 验证 SELECT + 2 条 `COMMENT ON COLUMN` + `/* 回滚块 */`，中文注释同时去乱码。因 `_migrations` 已按文件名登记该迁移，存量环境会被跳过，本次修复**只影响全新部署**（低风险）。（017/020/999，待修）建议同法重建；**020 需先确认生产的审计日志触发器是否已用其它途径补上**；999 更像报表脚本，建议移出迁移目录。

修复命令

（019，已完成）按原注释描述的意图重建为格式完好的迁移：`BEGIN` + **9 个 `DO $$ ... IF EXISTS (SELECT 1 FROM information_schema.columns WHERE ... numeric_precision = 12) ... END $$;` 幂等守卫**（bk_vouchers 2 列 / bk_voucher_entries 2 列 / bk_ledger_balances 4 列 / bk_douyin_orders 1 列）+ 验证 SELECT + 2 条 `COMMENT ON COLUMN` + `/* 回滚块 */`，中文注释同时去乱码。因 `_migrations` 已按文件名登记该迁移，存量环境会被跳过，本次修复**只影响全新部署**（低风险）。
（017/020/999，待修）建议同法重建；**020 需先确认生产的审计日志触发器是否已用其它途径补上**；999 更像报表脚本，建议移出迁移目录。

错误签名

迁移执行**无任何 Error/Exception 报错**，`migration_runner.py` 把文件名写入 `_migrations` 记为 applied，但 schema 毫无变化 —— `BEGIN;` / `ALTER TABLE ...;` / `COMMIT;` 全被行注释吞掉。实测 `019_v3_decimal_precision.sql` 字节 6554 / `LF=0`（整份文件一行），且自引入提交 `7e0ab82`（2026-07-18）起即如此。

技术信息

来源项目

project-02

涉及文件

database/migrations/019_v3_decimal_precision.sql, database/migrations/017_v3_comprehensive.sql, database/migrations/020_audit_log_triggers.sql +2

标签

project-02, database-schema