From 4a8703b037f77df61b322dbadf6c69e34b297ccc Mon Sep 17 00:00:00 2001
From: Xiaoxia AI <xiaoxia@localhost>
Date: Sun, 21 Jun 2026 07:49:23 +0800
Subject: [PATCH] ci: validate alembic migration chain

---
 .gitea/workflows/ci-cd.yml  | 13 ++++++++++---
 .github/workflows/ci-cd.yml | 13 ++++++++++---
 docs/SCHEMA-MAINLINE.md     |  6 +++---
 3 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/.gitea/workflows/ci-cd.yml b/.gitea/workflows/ci-cd.yml
index 9bd9f0333..869701c6a 100644
--- a/.gitea/workflows/ci-cd.yml
+++ b/.gitea/workflows/ci-cd.yml
@@ -61,12 +61,19 @@ jobs:
 
       - name: Run code quality checks
         run: |
-          python -m compileall -q apps packages tests
-          python -m black --check apps packages tests
-          python -m isort --check-only apps packages tests
+          python -m compileall -q alembic apps packages tests
+          python -m black --check alembic apps packages tests
+          python -m isort --check-only alembic apps packages tests
           python -m flake8 apps packages tests --count --statistics
           bandit -r apps packages -q
 
+      - name: Validate Alembic migrations
+        run: |
+          DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas \
+            python -m alembic upgrade head --sql > /tmp/alembic-upgrade.sql
+          test -s /tmp/alembic-upgrade.sql
+          grep -q "Running upgrade" /tmp/alembic-upgrade.sql
+
       - name: Run tests
         run: |
           python -m pytest tests -q
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 9bd9f0333..869701c6a 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -61,12 +61,19 @@ jobs:
 
       - name: Run code quality checks
         run: |
-          python -m compileall -q apps packages tests
-          python -m black --check apps packages tests
-          python -m isort --check-only apps packages tests
+          python -m compileall -q alembic apps packages tests
+          python -m black --check alembic apps packages tests
+          python -m isort --check-only alembic apps packages tests
           python -m flake8 apps packages tests --count --statistics
           bandit -r apps packages -q
 
+      - name: Validate Alembic migrations
+        run: |
+          DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas \
+            python -m alembic upgrade head --sql > /tmp/alembic-upgrade.sql
+          test -s /tmp/alembic-upgrade.sql
+          grep -q "Running upgrade" /tmp/alembic-upgrade.sql
+
       - name: Run tests
         run: |
           python -m pytest tests -q
diff --git a/docs/SCHEMA-MAINLINE.md b/docs/SCHEMA-MAINLINE.md
index 3f9d899ed..58697a2d2 100644
--- a/docs/SCHEMA-MAINLINE.md
+++ b/docs/SCHEMA-MAINLINE.md
@@ -25,6 +25,7 @@ staging / production 不允许依赖 `Base.metadata.create_all()` 建表；表
 - staging 数据库 `alembic_version` 已确认：`001`
 - staging health endpoint 已确认 healthy
 - `develop` 部署 job 已确认 succeeded
+- CI 已增加 Alembic offline upgrade SQL 生成检查，验证 migration 链可加载并能生成 `upgrade head` SQL
 
 ## 已废弃入口
 
@@ -55,9 +56,8 @@ staging / production 不允许依赖 `Base.metadata.create_all()` 建表；表
 
 后续 schema 工作应继续推进：
 
-1. CI 增加迁移检查：`alembic upgrade head`。
-2. 新增 revision drift 检查，防止 models 已改但未生成 migration。
-3. 对 production 首次接入 Alembic 前，先执行只读 schema/数据备份检查。
+1. 新增 revision drift 检查，防止 models 已改但未生成 migration。
+2. 对 production 首次接入 Alembic 前，先执行只读 schema/数据备份检查。
 
 ## 禁止事项