# `supabase/migrations/`

主业务 Supabase 的版本化迁移目录。`supabase db push` / `supabase db reset` 按文件名时间戳顺序应用。

## 命名规范

```
YYYYMMDDHHMMSS_short_description.sql
```

例如 `20260423000100_task_codes_and_search_result_task_id.sql`。

## 当前文件

| 文件 | 类型 | 说明 |
| --- | --- | --- |
| `2026041500{0100,0200}_remote_baseline_placeholder.sql` | placeholder | 远端 04-15 的 2 次手动 schema 修改 |
| `2026041600{0100,0200,0300,0400}_remote_baseline_placeholder.sql` | placeholder | 远端 04-16 的 4 次手动 schema 修改 |
| `2026041700{0100,0200}_remote_baseline_placeholder.sql` | placeholder | 远端 04-17 的 2 次手动 schema 修改 |
| `20260421000100_search_strict_contact_rule.sql` | 真实迁移 | 强制联系人规则 |
| `20260423000100_task_codes_and_search_result_task_id.sql` | 真实迁移 | 任务码 & search_result 关联 |
| `20260423000200_final_result_products_match_audit.sql` | 真实迁移 | 匹配审计字段 |
| `20260426000200_multi_provider_llm_config.sql` | 真实迁移 | 多 Provider LLM 配置与阶段路由 |

## 关于 `*_remote_baseline_placeholder.sql`

这 8 个 placeholder 是 Supabase CLI 与 Studio 「混合工作流」的副产物：

- 团队曾直接在 Supabase Studio 改远端 schema，未本地写迁移
- 远端 `supabase_migrations.schema_migrations` 表仍记录了这些 timestamp
- CLI 要求本地有同名文件以「续上历史」，否则 `supabase migration list` 会报 missing
- 文件本身只有一行 `-- Placeholder ...` 注释，**运行时是 NO-OP**

### 如何彻底清理（需要 DB 访问权限，本仓库不能自动完成）

1. 在能访问 prod Supabase 的环境跑：
   ```bash
   supabase db dump --data-only=false > supabase/migrations/20260415000000_baseline.sql
   ```
2. 删除 8 个 `*_remote_baseline_placeholder.sql`
3. 同步删除（或手工调整）`schema_migrations` 表中对应 8 条记录，让远端只认新的 baseline timestamp
4. 在新环境用 `supabase db reset` 验证从 baseline 一键重建

> 在没有真实 baseline 之前，**不要删除 placeholder 文件**——CLI 会把它们当作"被回滚的迁移"重新尝试应用，可能引发意外副作用。

## 添加新迁移

```bash
supabase migration new my_change_description
# 会生成 supabase/migrations/<timestamp>_my_change_description.sql
# 编辑该文件，然后：
supabase db push   # 推到远端
```

不要绕过 CLI 直接在 Studio 改 schema——会再次产生 placeholder 缺口。
