fix(shadow): align outbound predicates with site data for v3.3

Use the business project and captured site predicates, validate single-stock proposals, and skip unsupported scopes without changing Legacy. Add the guarded V3.3 SQL upgrade, CMD operations, regression tests and deployment runbook.

doc/algorithm-shadow/README.md

@@ -1,5 +1,7 @@
 # FT546WMS 影子 v3 现场操作手册
 
+已部署 V3/V3.1/V3.2 的现场升级到 V3.3，请先使用 [V3.3 升级和回滚步骤](SHADOW_V33_DEPLOYMENT.md)。下面保留最初 v2 到 v3 的历史操作说明，不要把“当前现场已有 v2”套用于已升级现场。
+
 ## 1. 这次部署做什么
 
 目标分支：`test/ft546wms-shadow-v3-20260903`。

doc/algorithm-shadow/SHADOW_V33_DEPLOYMENT.md

@@ -0,0 +1,114 @@
+# 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 效果、性能或正式切换已验收。