不需要自动迁移

docker/entrypoint-api.sh

@@ -5,35 +5,7 @@ echo "========================================="
 echo "君鸿卡管系统 API 服务启动中..."
 echo "========================================="
 
-# 构建数据库连接 URL（从环境变量读取）
-# 环境变量由 docker-compose 传入，格式为 JUNHONG_DATABASE_*
-DB_HOST="${JUNHONG_DATABASE_HOST:-localhost}"
-DB_PORT="${JUNHONG_DATABASE_PORT:-5432}"
-DB_USER="${JUNHONG_DATABASE_USER:-postgres}"
-DB_PASSWORD="${JUNHONG_DATABASE_PASSWORD:-}"
-DB_NAME="${JUNHONG_DATABASE_DBNAME:-junhong_cmp}"
-DB_SSLMODE="${JUNHONG_DATABASE_SSLMODE:-disable}"
-
-DB_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=${DB_SSLMODE}"
-
-echo "检查数据库连接..."
-for i in {1..30}; do
-    if migrate -path /app/migrations -database "$DB_URL" version > /dev/null 2>&1; then
-        echo "数据库连接成功"
-        break
-    fi
-    echo "等待数据库就绪... ($i/30)"
-    sleep 1
-done
-
-echo "执行数据库迁移..."
-if migrate -path /app/migrations -database "$DB_URL" up; then
-    echo "数据库迁移完成"
-else
-    echo "错误: 数据库迁移失败，拒绝使用旧结构启动 API"
-    exit 1
-fi
-
+# 数据库迁移由发布人员在维护窗口人工执行，应用启动不得自动修改数据库结构。
 echo "启动 API 服务..."
 echo "========================================="
 exec /app/api

docs/7月迭代/七月迭代联调交付说明.md

@@ -2,7 +2,7 @@
 
 ## 交付状态
 
-本说明覆盖 `deliver-july-iteration-confirmed-scope` 的企业微信、Gateway、Redis/Asynq、对象存储和前端联调输入。生产代码、增量迁移和 OpenAPI 已生成至可联调状态；仓库迁移已新增至 `000196`，测试环境下次部署时由 API 启动脚本自动执行，尚未执行自动化测试、完整构建、LSP 或真实外部环境闭环。
+本说明覆盖 `deliver-july-iteration-confirmed-scope` 的企业微信、Gateway、Redis/Asynq、对象存储和前端联调输入。生产代码、增量迁移和 OpenAPI 已生成至可联调状态；仓库迁移已新增至 `000196`，数据库迁移与 API 启动完全解耦，必须由发布人员在维护窗口人工执行并核对，尚未执行自动化测试、完整构建、LSP 或真实外部环境闭环。
 
 接口统一使用 `{code,msg,data,timestamp}` 响应。完整请求和响应结构以 `docs/admin-openapi.yaml` 为准。
 
@@ -127,11 +127,11 @@ API 与 Worker 必须连接同一 Redis/Asynq。新增或复用的任务如下
 - 卡限速不保存本地当前档位，结果未知必须人工向 Gateway 核对。
 - CSV 任务逐行部分成功，不保证整批业务原子性；任务详情是失败和跳过原因的权威展示。
 - 店铺登录限制不主动吊销既有 C 端 Token。
-- 测试库此前已完成 `000182`～`000194` 结构落库和注释核对；`000195`～`000196` 将在下一次测试环境部署时执行，外部系统闭环和前端浏览器验收尚未完成。
+- 测试库此前已完成 `000182`～`000194` 结构落库和注释核对；`000195`～`000196` 需要发布人员人工处理并核对迁移状态，API 容器启动不会执行或修复迁移，外部系统闭环和前端浏览器验收尚未完成。
 
 ## 发布和回滚
 
-1. 发布目标数据库必须执行至 `000196`，并核对 `tb_system_config` 已出现 6 个七月迭代默认配置、`tb_wecom_application` 已使用明文凭据字段；测试环境由 API 容器启动脚本自动迁移。
+1. 发布人员在维护窗口人工将目标数据库迁移至 `000196`，并核对 `tb_system_config` 已出现 6 个七月迭代默认配置、`tb_wecom_application` 已使用明文凭据字段；API 和 Worker 启动均不会自动执行、回滚或修复迁移。
 2. 先部署数据库兼容代码、API 和 Worker，保持旧审批入口开启；再配置企微应用、模板、回调和默认发起人。
 3. 真实审批闭环通过后，先隐藏前端旧按钮，再关闭旧入口配置并重启 API。
 4. 回滚时先停止新批量任务和新审批提交，等待已领取任务结束，再回退应用版本。新增表和列暂不删除。

docs/deployment/deployment-guide.md

@@ -295,14 +295,17 @@ docker-compose -f docker-compose.prod.yml restart worker
 ### 手动执行数据库迁移
 
 ```bash
-# 进入 API 容器
-docker exec -it junhong-cmp-api bash
+# 查看当前迁移版本；即使 API 未启动也可以执行
+docker compose -f docker-compose.prod.yml run --rm --entrypoint sh api -c '
+  DB_URL="postgresql://${JUNHONG_DATABASE_USER}:${JUNHONG_DATABASE_PASSWORD}@${JUNHONG_DATABASE_HOST}:${JUNHONG_DATABASE_PORT}/${JUNHONG_DATABASE_DBNAME}?sslmode=${JUNHONG_DATABASE_SSLMODE}"
+  migrate -path /app/migrations -database "$DB_URL" version
+'
 
-# 查看当前迁移版本
-migrate -path /app/migrations -database "$(cat /app/.env | grep DB_ | xargs)" version
-
-# 执行迁移（通常容器启动时会自动执行）
-migrate -path /app/migrations -database "$(cat /app/.env | grep DB_ | xargs)" up
+# 在维护窗口人工执行迁移；容器正常启动不会自动迁移
+docker compose -f docker-compose.prod.yml run --rm --entrypoint sh api -c '
+  DB_URL="postgresql://${JUNHONG_DATABASE_USER}:${JUNHONG_DATABASE_PASSWORD}@${JUNHONG_DATABASE_HOST}:${JUNHONG_DATABASE_PORT}/${JUNHONG_DATABASE_DBNAME}?sslmode=${JUNHONG_DATABASE_SSLMODE}"
+  migrate -path /app/migrations -database "$DB_URL" up
+'
 ```
 
 ### 回滚到旧版本