# FT546WMS 影子 V3.3：升级和回滚

适用现场：WMS 已运行影子 V3/V3.1/V3.2，数据库包版本为 `2026-09-03-3`。
分支仍为 `test/ft546wms-shadow-v3-20260903`。这不是正式算法切换。

## 这次改什么

自动出库影子请求的项目号改取出库明细 `spare4`，不再取仓库配置中的 `FT546`。
补齐产品、spare1/2/3、项目、fid 对电压、unit 对相别的可选筛选，以及库位锁定、状态、托盘一致性检查。
按计划数量减已分配数量观察。新旧输入通过 `predicate_version` 区分，不把历史样本重新认定为新版本通过。

共享规划器和 Legacy 存储过程、调用入口没有修改。升级只新增 `alg` 表的可空字段、替换影子刷新过程、使旧快照失效并更新影子包版本。保留决策日志和累计指标。

注意：影子后台仍会增加数据库读取和计算开销，不能承诺对性能绝对零影响。升级过程需要一次计划内短暂停机。

## 第一步：先准备，不停程序

让服务器 AI 核实 IDEA 当前运行的 **WMS** 项目目录、分支、提交号、环境变量和日志目录，备份本地配置，并导出现有影子日志。
不要操作 WCS 或 WCS 影子程序，也不要因进程里有 `wcs` 字样就停止它。

在已经确认的 WMS 项目根目录打开 CMD，执行：

```cmd
git status --short
git branch --show-current
git rev-parse HEAD
git fetch origin
```

保存当前提交号作为回退点。工作区有改动时先停止同步，让服务器 AI 保存和核对改动，不要强制覆盖。
获得本次已推送的交付提交号后，再执行 `git pull --ff-only` 并核对 `git rev-parse HEAD`。
本地未推送的代码不能靠服务器 `git pull` 获得，不要猜提交号。

IDEA 重新加载 Maven，使用当前可用的 JDK 17 和 Maven 3.9.11 编译测试。
首次可能需要下载 H2 测试依赖；H2 不进入运行包，依赖问题应在停机前解决。
程序运行期间不要点 Build Project、热替换或重启；可在独立准备目录做构建，确认完成后再安排维护窗口。

## 第二步：先在数据库备份副本演练

本地 Java 测试和 SQL 2016 语法解析不能代替 SQL Server 实际升级验证。
让服务器 AI/DBA 在隔离 SQL Server 上恢复备份（数据库名保持 `FT546-wms`），先验证升级成功、重复执行无破坏、升级失败可回滚。
不要在生产库创建“测试作业”，不要触发业务回放。演练失败就不进入下一步。

## 第三步：低峰时停止 WMS，升级影子表

1. 在 IDEA 停止当前那个 WMS 实例，确认其 PID 已退出。不要同时启动稳定 WMS 和影子 WMS。
2. 等待至少 130 秒，确认没有其他 WMS 影子实例仍在运行。
3. 在项目根目录的 CMD 执行下面命令（使用现有 Windows 集成认证）：

```cmd
call scripts\shadow-v3-install.cmd "10.6.22.6,1433" "FT546-wms" v33
```

必须看到 `V33_UPGRADE_OK`（重复执行为 `V33_ALREADY_INSTALLED`）和 `INSTALL_OK mode=v33`。
现场已有 V3，**不要用 `clean`，不要卸载后重装，不要执行旧版 v2 升级来绕过错误**。

遇到心跳、清单、字段或锁超时错误，保存完整输出并停止。脚本对本次变更执行事务回滚；不要修改 manifest 绕过检查。

## 第四步：只启动一次，保持影子配置

沿用现场已有 Run Configuration，只核对下面两个值，其他连接、日志和限流设置不要随意覆盖：

```text
FORTUCKY_SHADOW_ENABLED=true
FORTUCKY_ALGORITHM_MODE=SHADOW
```

在 IDEA 启动一次 WMS。记录启动时间和时区。不要设置 `ACTIVE`。
旧快照已失效，后台会重新生成；刚启动还没有新快照或样本，不代表需要再次重启。

先检查登录、查询，再由现场人员按正常流程验证入库、自动出库、手动出库。
让服务器 AI 仅做只读核对：

```sql
SELECT package_id, package_version FROM alg.shadow_package_manifest;
SELECT warehouse_id, snapshot_generation, snapshot_status, synchronized_at, last_error
FROM alg.shadow_snapshot_state WHERE warehouse_id = '01';
SELECT TOP (20) stockout_detail_id, project_no, product_id, requested_quantity,
       allocated_quantity, predicate_version, synchronized_at
FROM alg.shadow_outbound_request_snapshot
WHERE warehouse_id = '01' ORDER BY synchronized_at DESC;
SELECT TOP (30) * FROM alg.decision_log ORDER BY created_at DESC;
```

包版本应为 `2026-09-07-33`，新快照应为 `PUBLISHED`，正常长度的请求输入应有 `predicate_version=1`。
实际自动出库产生后，新日志应包含 `predicateVersion=1`；可用建议还应有真实的 `proposedStock` 和 `selectedProject`。
快照刷新由事件触发，没业务时同步时间不连续推进，不要仅凭这个重启。

## 出问题怎么回滚

最短路径：停止 WMS，在原 IDEA 配置里只把 `FORTUCKY_SHADOW_ENABLED` 改为 `false`，完整重启一次，再检查正常业务。
如仍异常，停止这个实例，使用第一步保留的原稳定源码和 Run Configuration 启动，仍保持影子关闭。
不要两个 WMS 同时运行；不要执行 `git reset --hard` 来覆盖现场配置。

紧急回滚不卸载数据库。新增的 `alg` 字段不参与 Legacy；保留它们和历史数据供排查。
若回到旧影子代码，也先关闭影子，避免用旧逻辑继续采集混杂样本。

确实需要完整卸载时，必须先备份影子数据、恢复稳定业务并停用影子，等待至少 130 秒，再由 DBA 执行：

```cmd
call scripts\shadow-v3-uninstall.cmd "10.6.22.6,1433" "FT546-wms" CONFIRM_UNINSTALL
```

卸载会删除全部本包 `alg` 对象及历史数据，只能从事先导出的证据/数据库备份恢复。它不是升级的必需步骤。

## 后续怎样判断

重新记录 V3.3 开始时间，只分析此次重启后的自然业务样本，建议覆盖至少 7 天及高峰。
继续使用 `shadow-v3-export.cmd`，让服务器 AI 同时提供准确分支、提交、IDEA 配置核对结果、完整日志和本次升级输出。
累计性能指标包含旧版本，必须用升级前后导出差值，不能当成 V3.3 单独指标。

本版保守跳过：多项目/多产品候选、候选超过 200 行、建议不在合格候选集、一托多库存行、单条库存不足以覆盖剩余数量，以及托盘已有作业。
现场动态 SQL 参数限长 80 字节；超长原始条件保留在快照，但标记版本 0，不作为有效输入。不会截断条件来凑匹配。
这些跳过不算通过。`READY` 只表示受支持范围内的库存建议通过核验，不证明完整出库流程、FIFO 效果、性能或正式切换已验收。