# 数据库迁移说明

## 当前结构

```
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 客户端（若未安装）：
   ```bash
   brew install libpq
   export PATH="/opt/homebrew/opt/libpq/bin:$PATH"
   ```

2. 生成 schema 基线（仅 DDL，不含数据）：
   ```bash
   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`（删除所有表）：
   ```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 全部幂等，安全）。