# Migration renumber — merge collision fix (2026-08-13)

## Problem

`main`（产品 ECR-009…016）与 Ops 线（ECR-013A…040）合并后，`000015`–`000023` **各有两套** migration。  
本仓 `internal/db.Migrate` 以**完整文件名**为 version，两边都可能被执行，但同号双文件易误导运维，也不兼容 golang-migrate。重编号消除歧义并固定依赖顺序。

## Canonical sequence (after fix)

| Ver | Name | Origin |
|-----|------|--------|
| 015 | ops_commerce | main Ops-D |
| 016 | ops_system | main Ops-E |
| 017 | unique_self_profile | main ECR-011 |
| 018 | admin_rbac | Ops ECR-013A |
| 019 | account_lifecycle | Ops ECR-013B |
| 020 | membership_plans | Ops |
| 021 | redemption_codes | Ops |
| 022 | ask_ops_read | Ops |
| 023 | content_safety_filter | Ops |
| 024 | ask_quality_feedback | Ops |
| 025 | ai_system_prompts | Ops |
| 026 | crisis_policies | Ops |
| 027 | user_avatar | main ECR-015 |
| 028 | mbti_label | main |
| 029 | mbti_questions | main |
| 030 | oejts_mbti | main |
| 031 | mbti_full_60 | main |
| 032 | home_daily_tips | main ECR-014 |
| 033–050 | knowledge…ops_hardening | Ops ECR-023…040 + hardening |

`000001`–`000014` 未改。

## Fresh database

```bash
# API 使用 internal/db.Migrate（version = 完整 stem，如 000018_admin_rbac）
cd apps/api && go run ./cmd/server   # 或集成测试 setup 会 Migrate
```

空库应写入 **50** 条 `schema_migrations`（已在 `yuxingu_mig_check` 验证）。

## Already-applied databases（必做）

本仓 version 键是 **完整文件名**（非纯数字）。重编号后若不改 `schema_migrations`，会把已执行过的 SQL **再跑一遍**。

对已有库先执行修复脚本：

```bash
psql "$DATABASE_URL" -f scripts/repair-schema-migrations-renumber.sql
```

然后再启动 API / `Migrate`。

### A. 可丢弃的开发库

重建库后 Migrate。

### B. 需保留数据

1. 跑 `scripts/repair-schema-migrations-renumber.sql`  
2. 再 Migrate（只会补尚未有的 stem）  
3. 若曾手改脏数据，对照 `SELECT version FROM schema_migrations ORDER BY version` 与本表核对  

分叉两边「同号不同义」时，必须以**实际 DDL**为准。

## Doc debt

ESS / Spec 里仍可能写旧号（如「migration 000015 = RBAC」）。以本文件与 `apps/api/migrations/` 文件名为准；后续 ECR 文档可逐步改引用。