# breeding 迁移机制

breeding 模块无 alembic 基线（表由 `create_all` 创建），直接 `alembic revision --autogenerate`
会试图重建全部表、风险高。故所有结构/数据变更统一走**幂等迁移脚本**：每支脚本可重复执行，
重复运行不产生副作用，单支失败不影响其余。

## 统一入口：run_migrations.py

按依赖顺序执行整套迁移，并依据数据库方言（`settings.DATABASE_TYPE`）自动跳过不支持的脚本：

| 脚本 | 作用 | PostgreSQL |
|---|---|---|
| fix_breeding_columns.py | ORM 与库列补齐（生成器改字段后同步） | ✔ |
| schema_align.py | 审计列统一新契约（uuid/is_deleted bool/审计 FK） | ✔ |
| align_columns.py | 业务必填列 NOT NULL 对齐（无 NULL 才收紧） | ✔ |
| add_unique_constraints.py | 业务唯一约束落库（部分唯一索引，未软删） | ✔ |
| migrate_dict_english.py | 字典存量中文 label → 英码 value | ✔ |

说明：
- 生产仅使用 PostgreSQL；PostgreSQL 专属语法（部分唯一索引 `WHERE is_deleted = false`、
  `gen_random_uuid()` 等）在非 postgres 方言下自动跳过并提示。
- 每支脚本均幂等；`--check` 仅对声明支持的脚本生效，不支持的（schema_align.py）在预览模式下跳过。

### 本地开发（Windows，conda `dpb`）

```powershell
cd backend
$env:ENVIRONMENT = "dev"
uv run python scripts/run_migrations.py --check   # 预览
uv run python scripts/run_migrations.py            # 执行
```
（无 uv 时可用 conda 环境的 `python` 替代 `uv run python`。）

### Docker 部署

```bash
cd docker
docker compose exec -T backend python /home/scripts/run_migrations.py
```
或直接 `deploy.sh migrate`（已接此入口）。容器内挂载 backend 代码到 `/home`，
`ENVIRONMENT` 由 compose 注入（prod 默认 postgres，runner 自动只跑适用迁移）。

## 单支脚本用法

每支脚本同样支持单独执行/预览：

```powershell
uv run python scripts/fix_breeding_columns.py --check      # 仅预览 DDL，不落库
uv run python scripts/fix_breeding_columns.py              # 执行补齐
uv run python scripts/schema_align.py                      # 审计列统一（幂等）
uv run python scripts/add_unique_constraints.py --check    # 唯一约束预览
uv run python scripts/add_unique_constraints.py            # 执行
uv run python scripts/migrate_dict_english.py --check      # 字典迁移预览
uv run python scripts/migrate_dict_english.py              # 执行（自动备份 bre_backup_*）
```

## 连接串来源

各脚本读取 `app.config.setting.settings.DB_URI / ASYNC_DB_URI`（与后端运行时一致），无需手动配置。

## 输出示例

```
[run_migrations] 数据库方言: postgres  模式: 执行
[run_migrations] 执行 fix_breeding_columns.py ...
[run_migrations] 执行 schema_align.py ...
[run_migrations] 执行 add_unique_constraints.py ...
[run_migrations] 执行 migrate_dict_english.py ...
[run_migrations] 全部迁移完成
```