# FT546WMS 影子 v3 现场操作手册

## 1. 这次部署做什么

目标分支：`test/ft546wms-shadow-v3-20260903`。

影子 v3 只观察算法建议，不改变 Legacy 分配结果。入库、自动出库、手动出库仍由原存储过程执行一次，原返回码、返回消息、库位和异常保持不变。正常业务请求只做固定大小的内存登记，不等待影子线程，也不在调用线程执行影子数据库、文件或同步日志操作。

影子后台会读取业务表，并且只写 `alg.*` 对象。它可能增加数据库 CPU 和 I/O，因此仍需低峰部署、监控和随时回滚。

## 2. 固定安全边界

- 现场只允许一个 FT546WMS JVM，稳定版和影子版不能同时运行。
- 仓库固定为 `01`；原始数据中的 `1` 与 `01` 等价，`W02` 只用于诊断，不能覆盖配置。
- SQL Server 必须使用 Windows 集成认证；脚本不接收用户名和密码。
- 当前现场已有 v2 包，安装必须使用 `upgrade`，不能使用 `clean`。
- v2 到 v3 升级保留 `alg.decision_log`；发现未知 `alg` 对象、清单不完整或 manifest 不匹配时脚本会停止。
- 影子失败、过期、并发、超时、配置错误或输入缺失均 fail-open：Legacy 继续，影子样本作废。
- 不执行正式 ACTIVE 切换，不增加 WCS/PDA/理库/预留/回放功能。

## 3. 部署前准备

现场负责人先记录：

- SQL Server 名称和数据库名；
- 当前 v2 测试开始时间和时区；
- IDEA 当前 Run Configuration；
- 当前稳定实例 PID 和端口；
- 本次交付给出的精确 v3 提交号 `<V3_COMMIT>`；
- 应用日志目录。

部署前先导出现有 v2 证据。不要卸载 v2：

```cmd
cd /d C:\project\FT546WMS-SHANDOW
call scripts\shadow-v3-export.cmd C:\project\FT546WMS-SHANDOW "<SQL_SERVER>" "<DATABASE>" "<V2_START_UTC>" "C:\project\FT546WMS-v2-before-v3" "<LOG_DIR>"
```

如果当前代码还没有 v3 导出脚本，先用既有导出方式保存 `alg.decision_log`、诊断结果、日志、分支和提交号，再继续。

## 4. 按顺序部署 v3

### 第一步：停止 IDEA 中的 v2 稳定实例

记录停止时间，在 IDEA 点 Stop。用下面命令确认最多只有一个相关 JVM，最好为 0：

```cmd
jps -lv | findstr /I "RuoYiApplication FT546WMS"
```

停止和重新启动之间会有一次短暂停机，这是计划内中断。不要同时启动两个实例来消除停机，否则可能重复执行定时任务、消费或外部回调。

### 第二步：同步精确分支和提交

```cmd
cd /d C:\project\FT546WMS-SHANDOW
git fetch origin
git switch test/ft546wms-shadow-v3-20260903
git pull --ff-only
git rev-parse HEAD
git status --porcelain
```

`git rev-parse HEAD` 必须等于交付的 `<V3_COMMIT>`，`git status --porcelain` 必须没有输出。若不一致，停止部署。

### 第三步：执行只读预检

```cmd
call scripts\shadow-v3-preflight.cmd C:\project\FT546WMS-SHANDOW <V3_COMMIT> "<SQL_SERVER>" "<DATABASE>"
```

只有看到 `PREFLIGHT_OK` 才能继续。预检检查分支、精确提交、干净工作树、main 祖先、JVM 数量、SQL 连接、v2/v3 manifest 和当前快照；它不修改数据库。

### 第四步：升级数据库包

当前现场是 v2，只执行：

```cmd
call scripts\shadow-v3-install.cmd "<SQL_SERVER>" "<DATABASE>" upgrade
```

只有全新测试数据库、确认没有 `alg` schema 时才允许使用 `clean`。现场生产库不要使用 `clean`。

### 第五步：设置 IDEA 环境变量

在影子 Run Configuration 中使用：

```text
FORTUCKY_SHADOW_ENABLED=true
FORTUCKY_ALGORITHM_MODE=SHADOW
FORTUCKY_ALGORITHM_DATABASE_WRITES_ENABLED=true
FORTUCKY_ALGORITHM_WAREHOUSE_ID=01
FORTUCKY_SHADOW_TIMEOUT_SECONDS=3
FORTUCKY_SHADOW_SNAPSHOT_MAX_AGE_SECONDS=60
FORTUCKY_SHADOW_QUIET_INTERVAL_MILLIS=1000
```

不要设置 `ACTIVE`，不要添加数据库密码，不要设置 replay、tidy、reservation 或 WCS callback 开关。

### 第六步：只启动一次影子实例

在 IDEA 启动 v3。不要重复点击 Run。启动时后台会认领唯一实例并建立第一代快照；认领或刷新失败只会关闭影子可用性，不应阻止 Legacy 启动。

启动后检查：

```cmd
jps -lv | findstr /I "RuoYiApplication FT546WMS"
```

只能看到一个 FT546WMS JVM。

### 第七步：做只读和受控业务检查

先完成登录、页面查询等只读检查，再由现场人员执行一笔受控入库、一笔自动出库和一笔手动出库。确认：

- Legacy 返回码、消息、库位和设备动作与稳定流程一致；
- 没有相同存储过程重复执行；
- `alg.shadow_snapshot_state` 为仓库 `01` 的 `PUBLISHED`；
- `alg.shadow_instance_heartbeat` 只有当前实例；
- `alg.decision_log` 出现新的计划/比较记录；
- 应用日志中的影子 warning 不包含业务载荷或异常消息。

## 5. 立即停止条件

出现任一情况立即执行第 7 节回滚：

- Legacy 结果、响应码、消息、库位或设备动作改变；
- 同一个 Legacy 存储过程疑似执行两次；
- 出现第二个 FT546WMS JVM；
- `alg` 之外出现本次部署造成的数据写入或新对象；
- WMS、WCS、PDA 或现场作业异常；
- 正常接口延迟或数据库 CPU、I/O、锁等待超过现场阈值；
- 快照长时间不是 `PUBLISHED`，或 `ERROR_*` 指标持续增长。

单条 `shadow_failure` 表示该影子样本失败开放，不等于 Legacy 失败；但必须记录时间并纳入分析。

## 6. 连续观察和七天导出

至少连续观察 7 天，覆盖正常业务高峰、入库、自动出库和手动出库。期间不要重放业务来补影子样本。

观察结束后运行：

```cmd
cd /d C:\project\FT546WMS-SHANDOW
call scripts\shadow-v3-export.cmd C:\project\FT546WMS-SHANDOW "<SQL_SERVER>" "<DATABASE>" "<V3_START_UTC>" "C:\project\FT546WMS-shadow-v3-export" "<LOG_DIR>"
```

成功时显示 `EXPORT_OK`。输出目录包含：

- `deployment.txt`：分支、提交、工作树；
- `runtime-processes.txt`：JVM 进程；
- `environment-variable-names.txt`：仅环境变量名，不含值；
- `sql-diagnostics.txt`：manifest、快照、心跳、输入覆盖、阻塞；
- `comparison-detail.txt`：比较汇总和完整决策行；
- `runtime-metrics.txt`：准入、跳过、错误和时延桶；
- `inventory-parity.txt`：Legacy 与已发布快照库存差异计数；
- `shadow-warnings.txt`：日志目录中的结构化影子 warning。

把整个输出目录压缩后交给分析，不要包含密码、令牌或与测试无关的个人信息。只有七天数据通过分析后，才讨论正式切换；本分支本身不执行 ACTIVE 切换。

## 7. 回滚

首选回滚只关闭影子，不卸载数据库对象：

1. 在 IDEA 停止 v3，记录停止时间；
2. 设置 `FORTUCKY_SHADOW_ENABLED=false`；
3. 完整重启一次；
4. 检查只有一个 JVM；
5. 做登录、查询、受控入库和出库冒烟检查。

更彻底的应用回滚是停止 v3，切回现场原稳定源码/提交并用原 Run Configuration 启动。无论哪种方式，都先恢复业务服务，再处理数据库对象。

`alg.*` 可以保留供取证，稳定 Legacy 不依赖它。不要把卸载当作紧急回滚步骤。

## 8. 可选卸载

只有满足全部条件才卸载：影子实例已停止、稳定服务已恢复、七天证据已导出并备份、DBA 已确认维护窗口。

```cmd
call scripts\shadow-v3-uninstall.cmd "<SQL_SERVER>" "<DATABASE>" CONFIRM_UNINSTALL
```

卸载器只接受精确口令 `CONFIRM_UNINSTALL`，并由 SQL 包再次校验 v3 manifest 和完整对象白名单。发现未知/缺失对象时会在删除前停止。不要修改 manifest 或脚本绕过保护。

## 9. 自动化验证与残余风险

- 本地单元/静态测试不能替代 SQL Server 2016 备份副本演练。
- `READ UNCOMMITTED` 只用于观察，可能看到业务事务中间状态。
- 单线程容量一队列限制影子后台并发，但不能消除数据库资源竞争。
- 3 秒 worker 等待超时不等于 JDBC/SQL Server 一定在 3 秒内完成取消或回滚。
- 影子调用线程不等待后台，但主机和数据库资源竞争仍可能间接影响 Legacy，需要现场监控。