zgw
699310e61d
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.
115 lines
6.6 KiB
Markdown
115 lines
6.6 KiB
Markdown
# 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 效果、性能或正式切换已验收。
|