FT546MWS/doc/algorithm-shadow/SHADOW_V33_DEPLOYMENT.md

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，执行：

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 集成认证）：

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，只核对下面两个值，其他连接、日志和限流设置不要随意覆盖：

FORTUCKY_SHADOW_ENABLED=true
FORTUCKY_ALGORITHM_MODE=SHADOW

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

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

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 执行：

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 效果、性能或正式切换已验收。