交付出件箱

给 root · 视光档案二期发生产 · 数据库迁移执行说明

dev2 · 2026-09-07 · 长官已批准发生产
需要 root 在生产容器里执行迁移;代码发布由 dev2 自己跑 release-to-prod。

一句话

生产库缺 7 个列,视光档案二期代码要读写它们。必须先跑迁移,再发代码,顺序反了门店端一打开就报错。

要跑的命令(就一条)

alembic upgrade batch5_ai_conclusion

🔴 为什么不能用 `alembic upgrade head`

迁移目录当前有 2 个 head:

head	属于	能否上生产
`batch5_ai_conclusion`	视光档案二期(本次要发的)	✅ 就是它
`34ec94466f0c`	机构洞察/谣言粉碎机等别的功能线	❌ 含 drop_table,不能上

裸 upgrade head 在多头情况下会报错或行为不确定,可能撞上那条含删表的链。必须显式点名版本。

迁移链(已验证连通,零 gap)

device_epoch_seat_kick   ← 生产当前版本(已 SELECT 确认)
  → seat_remark_name       (MR#565 引入)
    → batch5_ai_conclusion (MR#567 引入)

这两个迁移做什么(只加列,不删不改)

users 表加 1 列:

列	类型	可空
seat_remark_name	VARCHAR(50)	是

refractive_records 表加 6 列:

列	类型	可空
ai_analysis_text	TEXT	是
ai_analysis_status	VARCHAR(16)	是
ai_analysis_updated_at	TIMESTAMPTZ	是
store_conclusion_text	TEXT	是
store_conclusion_pushed_text	TEXT	是
store_conclusion_pushed_at	TIMESTAMPTZ	是

全部 nullable,无 backfill,无 DROP,无索引重建。存量数据保持 NULL,对现有功能零影响。
(两个文件的 upgrade() 已逐个 grep 确认:DROP 语句只出现在 downgrade() 里,不会被执行。)

跑完怎么确认成功

# ① 版本推进到位
psql -c "SELECT version_num FROM alembic_version"
# 期望: batch5_ai_conclusion

# ② 列真的加上了(这是真判据,别只看 alembic 版本号)
psql -c "SELECT column_name FROM information_schema.columns WHERE table_name='refractive_records' AND column_name LIKE 'ai_%' OR column_name LIKE 'store_conclusion%' ORDER BY 1"
# 期望: 6 行

psql -c "SELECT column_name FROM information_schema.columns WHERE table_name='users' AND column_name='seat_remark_name'"
# 期望: 1 行

出问题怎么回退

两个迁移都是纯加列,回退安全:

alembic downgrade device_epoch_seat_kick

回退会删掉上面 7 个列。因为是新列、存量全 NULL,不会丢任何业务数据。

时间窗建议

加列是瞬时操作(不重建表、不锁全表),生产表体量不大,不需要停机窗口。但仍建议避开门店营业高峰。

跑完通知 dev2

迁移落地后请告知,dev2 接着发代码(37 个 MR)。代码没发之前,新列空着不影响任何现有功能。