iTi-Flask/docs/MIGRATIONS.md

# 数据库迁移

## 规则

每个业务项目只保留一条 Alembic migration 流。

`migrations/versions` 必须提交到 Git。
运行时数据库文件不提交。

生产只从 `main` 升级：

```bash
flask db upgrade
```

## 分支模型

推荐分支模型：

- `main`：生产发布分支。
- `dev`：集成分支。
- `user/<name>`：个人开发分支。

`dev` 合并到 `main` 前必须只有一个 migration head。

## 文件名

migration 文件名使用日期、时间、revision 和 message slug。

`migrations/alembic.ini`：

```ini
file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
```

migration message 第一个词是作者名。
后面自由描述。

```bash
uv run python -m flask --app app.py db migrate -m "alice add workorder priority"
```

生成示例：

```text
20260508_1430_9f8a7c6d2e1a_alice_add_workorder_priority.py
```

## 合并多个 Head

个人分支合入 `dev` 前执行：

```bash
git fetch
git merge origin/dev
uv run python -m flask --app app.py db heads
uv run python -m flask --app app.py db current
uv run python -m flask --app app.py db upgrade
```

如果出现多个 head：

```bash
uv run python -m flask --app app.py db merge heads -m "alice merge heads before release"
uv run python -m flask --app app.py db upgrade
```

`dev` 应保持一个 head。

## 手工数据库变更

直接修改生产库结构不是正常流程。

如果发生紧急手工变更，必须当天补 migration，并把目标库恢复到一致的 Alembic 版本。

已经合并并部署过的 migration 不允许回头修改。

## 框架迁移

框架系统迁移会复制或同步到业务项目 migration 流。

业务项目生产仍然只执行一个命令：

```bash
flask db upgrade
```

同步命令：

```bash
flask iti migrations sync
```

默认同步到：

```text
migrations/versions
```

也可以指定目录：

```bash
flask iti migrations sync --target migrations/versions
```

该命令只复制业务项目缺失的框架 migration。
已有同名文件不会覆盖。