fix(shadow): repair UTC sampling and persist v3 diagnostics
This commit is contained in:
81
doc/algorithm-shadow/SHADOW_V32_UPDATE.md
Normal file
81
doc/algorithm-shadow/SHADOW_V32_UPDATE.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 影子 V3.2 更新、检查和回滚
|
||||
|
||||
本次只修复影子 UTC 时间映射、影子告警保存和 CMD 导出。Legacy 仍负责实际业务，不是正式算法切换。本次不需要安装、升级或卸载数据库对象，也不修改全局 JVM 时区。
|
||||
|
||||
## 第一步：选好短暂停机时间
|
||||
|
||||
现场由这一份 WMS 程序继续运行 Legacy，重启会短暂中断 WMS 服务。请选业务空闲的维护窗口，不要在作业处理中直接重启。
|
||||
|
||||
只停止 IDEA 中 `C:\project\FT546WMS-SHANDOW` 对应的 **WMS**。不要停止 WCS、WCS 影子或其他 Java 进程，不使用 `taskkill /IM java.exe`。
|
||||
|
||||
## 第二步：记录旧版本并更新代码
|
||||
|
||||
在 CMD 中逐行执行：
|
||||
|
||||
```cmd
|
||||
cd /d C:\project\FT546WMS-SHANDOW
|
||||
git branch --show-current
|
||||
git status --porcelain
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
分支必须是 `test/ft546wms-shadow-v3-20260903`，第二条 Git 检查必须没有输出。否则停止更新，让服务器 AI 汇报现有改动，不覆盖、不清理文件。
|
||||
|
||||
确认后，逐行执行；任何命令失败都停止：
|
||||
|
||||
```cmd
|
||||
git tag backup/ft546wms-before-v32-20260907 HEAD
|
||||
git fetch origin
|
||||
git pull --ff-only origin test/ft546wms-shadow-v3-20260903
|
||||
git rev-parse HEAD
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
如果备份标签已存在，不覆盖它，先让服务器 AI 核对。更新后的提交号应与本次交付提交一致，工作区仍应干净。
|
||||
|
||||
## 第三步：在 IDEA 重新编译并启动
|
||||
|
||||
保持原 Run Configuration、端口、数据库、许可证和环境变量。不要新开第二个 WMS。执行 Build / Rebuild Project，成功后启动原 WMS 配置。
|
||||
|
||||
关键变量仍然是：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
其他现有变量原样保留，不把这段当作整份环境变量的替代。不要添加 `-Duser.timezone=UTC`，不要放大快照有效期。
|
||||
|
||||
## 第四步：先确认采样，再累计测试时间
|
||||
|
||||
记录这次真正启动成功的北京时间和 UTC 时间。等现场自然发生正常业务，不制造、重放或重复提交出入库请求。让服务器 AI 按 `SHADOW_V3_SERVER_AI_EXPORT_PROMPT.md` 只读导出，将开始时间填为这次 V3.2 启动时间的 UTC 值。
|
||||
|
||||
检查以下证据：
|
||||
|
||||
- `ADMITTED` 在真实业务后增加；`ADMISSION_US` 只是检查次数，不代表采样成功。
|
||||
- `INBOUND_COMPARE` / `OUTBOUND_COMPARE` 开始产生，包含快照时间、代次和输入诊断。没有某类业务时不能要求对应计数增长。
|
||||
- `logs\shadow-diagnostics.log` 保存影子 WARN/ERROR，时间明确为 UTC。文件为空只表示本文件没有记录，不能单独证明影子可用。
|
||||
- 快照同步时间和新写入的 `flushed_at` 使用 UTC。旧累计指标不清零；旧行在首次新刷新前仍可能保留旧的本地时间，不能把所有历史时间强行减八小时。
|
||||
|
||||
`EXPORT_OK` 仅表示文件导出成功。`NO_COMPARISONS` 表示本窗口尚无入出库比较，不能批准切换。空闲后第一笔请求因快照超过 60 秒而跳过仍可能正常；不要为增加样本而关闭过期或并发保护。
|
||||
|
||||
时间映射修复有本地回归测试，但现场还需确认刷新错误、业务频率等其他因素是否影响采样。开始产生有效样本之后再累计观察期，仍按连续七天、至少 100 个有效入库和 100 个有效出库比较及原性能门槛评估，不按程序开了几天直接切换。
|
||||
|
||||
## 出现问题时回滚
|
||||
|
||||
如果更新后影响现有使用，先停止这一份 WMS，WCS 不动。只在工作区干净时执行：
|
||||
|
||||
```cmd
|
||||
cd /d C:\project\FT546WMS-SHANDOW
|
||||
git status --porcelain
|
||||
git switch --detach backup/ft546wms-before-v32-20260907
|
||||
```
|
||||
|
||||
在 IDEA Rebuild Project 后，用原配置启动，恢复更新前代码。若有未提交改动或命令报错，停止操作，不用 reset/clean 强制覆盖。
|
||||
|
||||
另一种隔离方式是在维护窗口将原配置中的 `FORTUCKY_SHADOW_ENABLED` 改为 `false` 后重启 WMS，停止影子观察，Legacy 继续运行。两种方式均不回滚业务数据、不卸载 `alg` 表，保留日志和影子数据用于排查。
|
||||
@@ -9,9 +9,9 @@
|
||||
- 仓库目录：C:\project\FT546WMS-SHANDOW
|
||||
- SQL Server：<SQL_SERVER>
|
||||
- 数据库：<DATABASE>
|
||||
- v3 测试开始 UTC：<V3_START_UTC，例如 2026-09-03T08:00:00>
|
||||
- 本次修复实际启动 UTC：<V3_START_UTC，例如 2026-09-07T02:00:00>
|
||||
- 应用日志目录：<LOG_DIR>
|
||||
- 输出目录：C:\project\FT546WMS-shadow-v3-export
|
||||
- 输出目录：C:\project\FT546WMS-shadow-v3-export（必须为空或不存在；重复导出用新的带时间目录）
|
||||
- 期望分支：test/ft546wms-shadow-v3-20260903
|
||||
- 期望提交：<V3_COMMIT>
|
||||
|
||||
@@ -30,12 +30,13 @@ git rev-parse HEAD
|
||||
git status --porcelain
|
||||
jps -lv | findstr /I "RuoYiApplication FT546WMS"
|
||||
|
||||
必须满足：分支等于期望分支，HEAD 等于期望提交，git status 没有输出，相关 JVM 最多一个。否则停止并报告。
|
||||
必须满足：分支等于期望分支，HEAD 等于期望提交，git status 没有输出，目标 WMS 正常运行且只有一个实例。结合源码目录和 IDEA 配置辨认，不把 WCS 或 WCS 影子算作 WMS；无法辨认就报告，不停止任何进程。
|
||||
|
||||
然后执行仓库自带的只读导出器：
|
||||
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。随后只检查输出文件是否存在，不打开或改写内容：
|
||||
必须看到 EXPORT_OK。此标记仅表示导出完成，不代表样本合格或可以正式切换。导出器已兼容 sqlcmd 13，无需改写 :out 或单独执行 SQL 文件。
|
||||
随后检查输出文件：
|
||||
dir /b C:\project\FT546WMS-shadow-v3-export
|
||||
|
||||
期望至少包含：
|
||||
@@ -55,6 +56,11 @@ shadow-warnings.txt
|
||||
- 输出目录；
|
||||
- 文件名和大小；
|
||||
- 任何错误。
|
||||
- comparison-detail.txt 汇总中的四项计数及 sample_status；NO_COMPARISONS 表示尚无比较样本，不当成测试通过。
|
||||
- 日志目录是否存在 shadow-diagnostics.log；没有报错时允许为空，不人为制造业务异常验证。
|
||||
- IDEA 中实际 WMS 启动时间、时区和 Run Configuration 是否可确认；不能确认的写明未知，不从启动 CMD 环境推断运行进程继承情况。
|
||||
|
||||
runtime-metrics.txt 是累计指标，不受本次开始时间过滤。V3.2 新写入 flushed_at 为 UTC；未被新刷新更新的旧行仍可能是旧本地时间。不要清零计数、改写旧时间或自行得出性能无影响的结论。
|
||||
|
||||
不要在回复中粘贴环境变量值、数据库凭据或完整业务数据。不要压缩以外的改写；由现场人员把整个输出目录压缩后交给分析。
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user