fix(shadow): capture and validate inbound task evidence for v3.4

doc/algorithm-shadow/SHADOW_V34_DEPLOYMENT.md

@@ -0,0 +1,80 @@
+# FT546WMS 入库影子 V3.4
+
+这是影子采集与比较修复，不是正式算法切换。现场继续由 `dbo.proc_allot_space` 分配货位。
+
+## 修复范围
+
+- 入库输入从 `mydo_job` 和 `mydo_job_detail` 采集，不再依赖入库单是否仍在活动表。
+- 影子请求标识采用 `job_id`，项目采用任务 `line_id`；采集明细 `spare1/2/3` 和任务 `fault_flag`。
+- 保存明细总数、不同分组字段组合数、不同产品/批次组合数、重复任务数量，不用第一条明细代表整个托盘。
+- 货位快照新增真正的 `this_cargo_area`，不把 `cargo_area_id` 当成 A/B/C/D 库区。
+- 新输入标记 `predicate_version=1`；决策原因标记 `inboundPredicateVersion=1`。旧样本不能重新认定为新版本通过。
+- 共享规划器、业务调用入口、Legacy 存储过程和出库影子规则不变。
+
+## 比较口径与限制
+
+新算法仍按原优化策略提出建议。只有建议通过保守的 Legacy 可选范围核验，且 Legacy 返回成功码 `10`，才可能记为 `MATCH` 或 `DIFFERENT`。
+
+目前可核验的是单产品/批次、分组字段一致的项目入库：候选空闲、未锁定、无托盘/库存、A/C 区、楼层无入库作业、通道无入出库作业或锁定，并且整条通道为空，或通道内有托盘一致且项目及 spare1/2/3 全匹配的库存。
+
+这是 `STRICT_GROUP_OR_EMPTY` 保守子集，不声称完整复刻 Legacy 排序。Legacy 的项目数量分支有按 `group_coding` 分组后赋值的歧义；严格分组匹配在两个分支内均属可选范围。`fault_flag=0` 的 C 区优先属于旧排序偏好，保留字段供分析，不替换共享规划器排序。
+
+Legacy 的部分货位约束和重复任务判断不限定仓库，因此刷新前后的货位、任务及任务明细签名覆盖全局。其他仓库变动也可能使本轮影子快照失效；存在快照之外的货位时，入库只记录跳过。此限制有意保留，不能靠删除检查来扩大通过率。现场验收还需测量全局读取增加的开销。
+
+以下情况记录具体原因，不能算通过：
+
+| 原因码 | 含义 |
+|---|---|
+| `SKIPPED_MISSING_PREDICATE_INPUT` | 旧快照或字段超过 Legacy 参数长度 |
+| `SKIPPED_MISSING_TASK_DETAILS` | 采到了任务，但没有任务明细 |
+| `SKIPPED_AMBIGUOUS_LEGACY_FIELDS` | 明细 spare1/2/3 不一致，无法复现 Legacy 无排序的 TOP (1) |
+| `SKIPPED_MULTI_PRODUCT_INPUT` | 单产品请求无法表示整个多产品/批次托盘，或缺少产品 |
+| `SKIPPED_AMBIGUOUS_TRAY_JOB` | 同托盘或任务号存在多个任务 |
+| `SKIPPED_INCOMPLETE_LEGACY_SCOPE` | 存在快照之外的仓库货位，不能用局部快照核验全局 Legacy 约束 |
+| `SKIPPED_UNSUPPORTED_COMMON_PROJECT` | 空项目、999 或 COMMON 的通用件映射及单深池策略尚需单独验证 |
+| `SKIPPED_LEGACY_CONSTRAINT` | 建议不在保守可选范围内；原因保留 `unverifiedProposal` |
+
+受控混放、借池和放宽分组等优化建议可能落在此范围外。这不等于建议必然错误，但不能在尚未确认这些规则的情况下当作兼容性通过。
+
+2026-09-07 的任务 31331 / 31333 分别有 45 / 35 条明细且 spare1 有不同值。修复后这类任务不再因缺少入库单被漏采，但仍应标为明细歧义，而不是强行改成通过。需要另行确定多明细业务规则后才能扩大验证范围。
+
+## 部署准备
+
+1. 先确认交付的提交号和已验证的 JAR，不要使用尚未推送的本地修改，也不要把带开发配置的原始 `target/ruoyi-admin.jar` 直接用于现场。
+2. 沿用现场离线 JAR 加外部配置方式，保留现有 JAR、外部配置和 IDEA 启动项用于回退。新 JAR 应按既有交付流程剥离内置连接配置并核对 SHA-256。
+3. 在隔离 SQL Server 上演练升级、重复执行和失败回滚。本地 H2 投影/Mapper 测试及 SQL 2016 解析不能代替真实 SQL Server 升级测试。
+4. 记录升级前的数据库包版本、影子指标、启动时间和业务基线。本包只从 `2026-09-07-33` 升至 `2026-09-07-34`，增加 11 个可空列，保留影子历史日志。
+
+## 维护窗口操作
+
+停止 WMS 的影子启用实例，确认退出并等待至少 130 秒。不要停止 WCS 或 WCS 影子程序，不要同时运行两个 WMS。
+
+在服务器已确认的新版本源码目录，用 CMD 执行：
+
+```cmd
+call scripts\shadow-v3-install.cmd "lpc:." "FT546-wms" v34
+```
+
+必须看到 `V34_UPGRADE_OK`（重复执行为 `V34_ALREADY_INSTALLED`）以及 `INSTALL_OK mode=v34`。
+已有 V3.3 不要用 `clean`、不要先卸载，也不要改清单绕过心跳检查。失败则停止后续部署并保存输出。
+`clean`/`upgrade` 模式会依次安装历史基础包、V3.3、V3.4，每个阶段单独提交；中间失败不代表之前阶段已回滚。`v34` 单步升级为一个事务。
+
+启动前再执行只读结构检查，必须返回 `V34_SCHEMA_OK`：
+
+```cmd
+sqlcmd -S "lpc:." -d "FT546-wms" -E -b -r1 -i "scripts\shadow-v34-schema-check.sql"
+```
+
+该检查核对 V3.4 对象、继承列及新增列的类型、长度、精度和可空性，并检查刷新过程的版本标记。没有成功标记就不要继续。原 `shadow-v3-preflight.cmd` 也包含这项检查，但它还要求新鲜的已发布快照，不适合直接用在升级完成但尚未启动的 `INITIALIZING` 状态。
+
+确认数据库完成后，再启动新 JAR，仅保留 `FORTUCKY_SHADOW_ENABLED=true`、`FORTUCKY_ALGORITHM_MODE=SHADOW`，不启用 ACTIVE。现有连接、内存、限流和日志配置不随意覆盖。
+
+## 启动后检查与回滚
+
+检查包版本为 `2026-09-07-34`，新快照为 `PUBLISHED`。通过自然业务观察入库，不制造生产测试单，不回放已完成任务。快照在事件触发时更新，没有新任务时输入表为空不等于故障。
+
+继续用现有 `shadow-v3-export.cmd` 导出，提供准确升级时间、提交、JAR 哈希和日志；只分析含 `inboundPredicateVersion=1` 的升级后记录。累计性能指标用升级前后差值评估，关注后台读取增加的开销。
+
+有异常时：停止新 WMS，将影子关闭，使用保留的原 JAR/源码及外部配置启动一个 WMS。无需卸载数据库，新列不参与 Legacy。回到旧代码也保持影子关闭，避免继续采集旧口径样本。
+
+本次代码修复不代表具备正式切换条件。所有跳过均需单独统计，不能用连续运行天数代替支持范围、样本覆盖和性能验收。