# 数据库迁移

## 规则

每个业务项目只保留一条 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
```

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 不允许回头修改。

## iTi-Flask 迁移

iTi-Flask 不提供业务表迁移和系统表迁移。

框架只初始化 Flask-Migrate。
业务项目自己的模型由业务项目生成 migration。

## 系统迁移

需要用户、角色、菜单等系统能力时，业务项目应依赖 `iti-system`。

`iti-system` 提供系统 migration 同步命令：

```bash
uv run python -m flask --app app.py iti-system migrations sync
uv run python -m flask --app app.py db upgrade
```

`iti-system` migration 是全量系统表集合。
不按 auth、user、role 等能力拆分。
实际项目如果只需要 ERP Service 这类轻服务，直接不依赖 `iti-system`。