junhong_cmp_fiber/migrations

数据库迁移说明

当前结构

migrations/
├── 000114_squash_baseline.up.sql   ← ⚠️ 待创建（见下方说明）
├── 000114_squash_baseline.down.sql ← ⚠️ 待创建
├── 000115_init_data.up.sql         ← 初始化数据（轮询配置 + purchase_role 回填）
├── 000115_init_data.down.sql
├── 000116_remove_legacy_commission_fields.up.sql  ← 删除废弃分佣字段
├── 000116_remove_legacy_commission_fields.down.sql
└── archive/                        ← 已归档的历史迁移（000000~000113）

⚠️ 发布前必做：生成 000114 squash 基线

背景：历史迁移（000000-000113）已归档，但尚未生成汇总基线文件。 现有测试环境的表是在 migrate 工具之外创建的，不受影响。 但全新环境（本地搭建、CI、生产首次部署）必须有 000114 才能通过 migrate up 建表。

执行时机：正式发布前，确认 schema 已稳定后执行一次。

步骤：

1. 安装 PostgreSQL 客户端（若未安装）：

   brew install libpq
   export PATH="/opt/homebrew/opt/libpq/bin:$PATH"
   

2. 生成 schema 基线（仅 DDL，不含数据）：

   PGPASSWORD=<密码> pg_dump \
     --schema-only --no-owner --no-acl \
     -h <host> -U <user> -d <dbname> \
     > migrations/000114_squash_baseline.up.sql
   

3. 在生成的 000114_squash_baseline.up.sql 头部加上注释（参考其他迁移文件格式）。

4. 创建 000114_squash_baseline.down.sql（删除所有表）：

   -- 回滚：删除所有业务表（谨慎执行）
   DROP TABLE IF EXISTS tb_wechat_config CASCADE;
   DROP TABLE IF EXISTS tb_tag CASCADE;
   -- ... 其他表（按依赖倒序）
   

5. 找 AI 协助完成 down.sql 和验证步骤（在全新数据库执行 migrate up 验证链路）。

6. 更新 scripts/reset_db.sh 中的注释，确认脚本可用。

迁移链路（目标状态）

全新数据库
  └─ migrate up
       ├─ 000114: 建表（squash 基线）
       ├─ 000115: 写初始化数据
       └─ 000116: 删除废弃字段

现有测试环境说明

测试环境的表通过历史方式创建，schema_migrations 中仅记录版本 116。 对正在运行的服务没有影响。 若需在测试库补齐迁移记录，可手动运行 migrate up（000115 全部幂等，安全）。