fix: validate explicit migrations and preserve large business ids

deploy/docker/README.md

@@ -15,7 +15,22 @@
 - 后端仅绑定 `127.0.0.1:9602`，前端仅绑定 `127.0.0.1:9601`。
 - 宝塔 `sw2.fuhua91.com` 代理至 9601，前端容器将 `/api/` 转发至后端并去除前缀，支持 WebSocket、SSE 和文件上传。
 
-数据库沿用已迁移并验证的 `sw10`，平台别名为 `lx/hw/yq/oa`，其中三个 SDK 别名连接 `game_lx/game_hw/game_yq` 测试库，Redis 沿用当前关闭状态。生产配置使用 `admin.app.env: production`，关闭开发 Swagger。七条常规任务启用（四条商务/区服日汇总、预警检测、两条有效端刷新），两个历史回填停用。**使用同一 sw10 时只运行一个调度实例，切换到服务器前停止本机的后端服务。**
+数据库沿用已迁移并验证的 `sw10`，设置 `admin.system.disable_auto_migrate: true`，由部署前的独立迁移命令更新结构。平台别名为 `lx/hw/yq/oa`，其中三个 SDK 别名连接 `game_lx/game_hw/game_yq` 测试库，Redis 沿用当前关闭状态。生产配置使用 `admin.app.env: production`，关闭开发 Swagger。七条常规任务启用（四条商务/区服日汇总、预警检测、两条有效端刷新），两个历史回填停用。**使用同一 sw10 时只运行一个调度实例，切换到服务器前停止本机的后端服务。**
+
+## 数据库迁移
+
+新副本必须先完整复制旧商务数据库，再执行 [旧框架转换 SQL](../migrations/legacy-framework.sql)，最后使用本次发布的后端执行全部增量迁移：
+
+```bash
+/app/kratos-admin -conf /data/conf/config.yaml -migrate
+/app/kratos-admin -conf /data/conf/config.yaml -check-schema
+```
+
+框架转换 SQL 的 `USE` 默认指向 sw10，其他目标库需修改该行。`-migrate` 使用与服务相同的模块迁移目录，包含新表、字段、索引、权限及任务定义，完成检查后退出；不会启动 HTTP、定时任务或 SDK 连接。`-check-schema` 只读检查版本、必需表和字段、主键与索引。旧业务表缺失时应重新完成复制，不能用空表替代历史数据。
+
+转换 SQL 和增量迁移必须全部执行。服务关闭自动迁移后，会在连接失败、版本未完成或结构缺失时明确报错，不进入初始化向导。新增迁移需同时更新模块结构检查与相邻回归测试。部署脚本在停止旧调度实例后自动运行 `-migrate`，全部检查通过才启动新服务。
+
+旧库 `tab_promote.id` 的 INT 自增容量由增量迁移扩大为同符号 BIGINT，保留现存 ID、自增高水位、关联数据与注释。渠道、玩家、流水等可能变大的旧业务 ID 在 JSON 和 Excel 中使用文本，请求兼容十进制字符串；不降低自增值或重新编号。
 
 ## 构建与发布
 
@@ -35,9 +50,9 @@ bash /www/wwwroot/sw2.fuhua91.com/releases/<commit>/deploy.sh <commit> --build-o
 bash /www/wwwroot/sw2.fuhua91.com/releases/<commit>/deploy.sh <commit>
 ```
 
-脚本先构建和检查镜像，再停止当前受管容器，保留一份停止的 `-previous` 容器。健康检查失败时恢复前一组容器。配置、上传文件和数据库不随镜像替换；索引迁移由后端启动按版本执行。
+脚本先构建和检查镜像，再停止当前受管容器，保留一份停止的 `-previous` 容器。迁移或健康检查失败时恢复前一组容器。配置、上传文件和数据库不随镜像替换；索引在独立迁移容器中按版本执行。
 
-首次启动持续等待建表与索引迁移完成，以后端健康检查通过为准，不设置总等待时限。容器退出或重启时立即回退；迁移日志记录每一步的名称、结果和耗时。切换数据库前需备份运行配置；镜像回退不会自动还原数据库连接配置。
+迁移不设置总等待时限，日志记录每一步的名称、结果和耗时；耗时索引完成前不会启动业务服务。业务容器退出或重启时立即回退。切换数据库前需备份运行配置；镜像回退不会自动还原数据库连接配置或撤销已执行的数据库迁移，回退版本需兼容当前结构和迁移版本。
 
 首次接入域名时，备份宝塔原站点配置，再安装 `bt-nginx-sw2.fuhua91.com.conf` 至 `/www/server/panel/vhost/nginx/`，执行 `/www/server/nginx/sbin/nginx -t` 通过后重载。模板保留证书验证目录，当前监听 HTTP；后续由宝塔为 sw2 单独配置匹配域名的证书。
 

deploy/docker/build-package.ps1

@@ -47,6 +47,7 @@ try {
     foreach ($name in @('deploy.sh', 'wait-backend.sh', 'bt-nginx-sw2.fuhua91.com.conf')) {
         Copy-Item -LiteralPath (Join-Path $PSScriptRoot $name) -Destination (Join-Path $stage $name)
     }
+    Copy-Item -LiteralPath (Join-Path $PSScriptRoot '..\migrations') -Destination (Join-Path $stage 'migrations') -Recurse
     & tar -czf $archive -C $stage .
     if ($LASTEXITCODE -ne 0) { throw 'Release archive failed' }
     $hash = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash.ToLowerInvariant()

deploy/docker/deploy.sh

@@ -91,6 +91,12 @@ for name in "${NAMES[@]}"; do
     fi
 done
 
+echo 'Applying and verifying database migrations before starting the service.'
+docker run --rm --name sw2-migrate --label com.sw2.application=sw2 \
+    --network "$NETWORK" --env-file "$BASE_DIR/runtime.env" \
+    -v "$BASE_DIR/config:/data/conf:ro" -v "$BASE_DIR/log:/app/logs" \
+    "$BACKEND_IMAGE" /app/kratos-admin -conf /data/conf/config.yaml -migrate
+
 created+=(sw2-backend)
 docker run -d --name sw2-backend --label com.sw2.application=sw2 \
     --restart unless-stopped --network "$NETWORK" \