iTi-Flask/docs/MIGRATIONS.md

数据库迁移

规则

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

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

生产只从 main 升级：

flask db upgrade

分支模型

推荐分支模型：

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

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

文件名

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

migrations/alembic.ini：

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

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

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

生成示例：

20260508_1430_9f8a7c6d2e1a_alice_add_workorder_priority.py

合并多个 Head

个人分支合入 dev 前执行：

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：

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 同步命令：

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。