81 lines
8.3 KiB
Markdown
81 lines
8.3 KiB
Markdown
# 2026-09-09 影子采集恢复与延迟比较修复
|
||
|
||
适用现场源码基线：`af8b5f1`，分支 `optimize/wcs`，目录 `C:\project\FT546-WCS-SHANDOW`。
|
||
|
||
本次交付供影子程序继续采样验证，不能据此切换正式调度。代码变更范围为 `ruoyi-wcs-shadow`；不改正式调度模块、生产数据、生产只读视图、数据库权限、PLC/WMS 通讯路径。本次无需执行 SQL 迁移或清理数据。
|
||
|
||
新运行标签：`ft546-shadow-20260909-recovery-pairing-v3`。
|
||
|
||
## 修复内容
|
||
|
||
### 完成的读取超时可以恢复
|
||
|
||
旧版本一次 `SOURCE_BATCH_DEADLINE_EXCEEDED` 或 `SOURCE_QUERY_TIMEOUT` 就永久停止采集。新版本确认读取线程及其源库事务已退出后，按 1、2、4、8、30 秒退避；后续成功读取可恢复 `READY`。调度仍遵守原配置的固定轮询间隔，退避期间不查询源库。
|
||
|
||
以下情况仍停止采集：整体执行超时或线程中断而不能确认工作已结束、源库事务提交/回滚失败、检测到重叠读取、影子证据存储或运行状态写入失败、容量保护触发。不会通过启动额外工作线程绕过保护。
|
||
|
||
初始运行状态发布单列为 `RUNTIME_PUBLICATION`。源库读取额度从实际执行读取时开始计算，最多 4 秒，并受整个周期剩余预算约束。默认总预算仍为 10 秒；状态发布已花费 7 秒时最多只剩 3 秒，不再重新给执行线程完整的 10 秒。初始同步状态写入仍由证据库 JDBC 自身的连接/查询超时约束；返回后会检查是否已耗尽周期预算。
|
||
|
||
### 将预测与随后出现的同阶段旧命令比较
|
||
|
||
待下发时的旧 `path_info` 可能属于前一阶段，因此原预测记录及其 `SOURCE_GAP` 必须保留。新程序在后续观测记录上追加 `shadow_difference.category = DEFERRED_COMPARISON`，不修改旧记录和旧哈希。
|
||
|
||
配对要求：
|
||
|
||
- 前一成功采样已将该阶段预测提交到影子证据库；后一采样看到普通阶段由 `issued=0 / execution_status=1` 转为 `1 / 3`。
|
||
- GUID、创建时间、任务号、任务类型、起终点、楼层、绑定车辆、货位、优先级及 default02～default08 保持一致。空字符串与 null 的非实质差别统一处理。
|
||
- 两次源库采样时间顺序正确、间隔不超过 30 秒，地图内容不变，活动队列 GUID 没有重复歧义。
|
||
- 旧命令路径可按现有协议投影，并且其起点仍对应预测时的阶段起点；无法证明时记录不可比较。
|
||
|
||
该比较只证明两次队列观测之间的关系，不是 PLC 接收确认，也不是在同一瞬时状态下执行两种算法的严格对照。交通状态可能在采样间变化，差异仍需逐条解释。
|
||
|
||
| reason_code | 含义 |
|
||
| --- | --- |
|
||
| `DEFERRED_MATCH` | 该次有效配对的车辆、路径、队列字段及虚拟协议写入一致 |
|
||
| `DEFERRED_DIFFERENCE` | 有可用配对，但至少存在一项差异；明细在 `actual_json.comparisons` |
|
||
| `DEFERRED_UNAVAILABLE` | 曾有候选预测，但阶段身份、旧路径或起点条件不满足；不计为匹配或算法不一致 |
|
||
|
||
`actual_json` 含 `predictionCycleId`、`predictionInputHash`、`predictionEvidenceHash`、预测及观测时间、队列内容哈希和比较明细。引用的 cycleId 使用数据库实际返回的 ID，包含去重重放的情况。
|
||
|
||
后一周期仍为 `OBSERVATION_ONLY`，不生成新编码写入。原始预测已产生的虚拟编码保留在原周期。同一待下发区间持续出现多次时，使用最后一次成功提交的预测；已下发后持续观察不会反复计数。同一完整输入紧邻重放时保留原比较内容和哈希。
|
||
|
||
候选只保留上一成功采样的最多 500 条紧凑预测，不保留整批输入 JSON。采样失败、事实无效、任务消失、进程重启或时间间隔过大时不会跨越缺口配对。特殊交接阶段保持仅观察。无法配对的普通观测也可能没有 `DEFERRED_COMPARISON` 行，不能将“没有差异行”解释为通过。
|
||
|
||
## 现场更新
|
||
|
||
现场依然通过 IDEA 运行源码。与操作人员逐步进行，每步确认完成后再给下一步。
|
||
|
||
1. 只停止 IDEA 中的 `Ft546ShadowApplication`。不要停止 `RuoYiApplication`，不要使用 Stop All 或批量结束 Java。
|
||
2. CMD 进入 `C:\project\FT546-WCS-SHANDOW`，执行 `git status --short`，保留现场配置和已有证据。若源码有重叠修改，先核对，不强制覆盖。
|
||
3. 执行 `git fetch origin optimize/wcs`，再使用交付消息指定的准确提交执行 `git merge --ff-only <交付提交号>`。执行 `git log -1 --oneline` 核对。
|
||
4. IDEA 刷新 Maven。沿用 Java 8、Maven 3.6.0 及现有离线仓库，编译影子模块和依赖。需要 CMD 编译时，在 Maven 已加入 PATH 的 CMD 中运行 `mvn -o -pl ruoyi-wcs-shadow -am test`；否则使用现场已有的 Maven 完整路径。
|
||
5. 沿用现有数据库账号、只读源库连接、独立证据库、18091 本机端口、轮询间隔及容量上限。安全等待/避让点保持原配置，不凭推测新增。
|
||
6. 本次启动使用新的运行记录，不复用旧 `runId`。人工 artifact/configuration 哈希按当前源码和现场配置重新计算；具体规则见 [9 月 8 日说明](ft546-shadow-20260908-phase-storage-repair.md#idea-中两个人工哈希字段)，不要把密码或配置快照提交到 Git。
|
||
7. 只启动 `com.ruoyi.shadow.Ft546ShadowApplication`。在服务器本机浏览器访问 `http://127.0.0.1:18091/shadow/status`，核对新 buildId、启动检查全部 PASS、`READY`，间隔至少一个采样周期刷新后 `lastCompletedCycle` 应继续前进。`evidenceBacklog=0` 单独不能证明正在采集。
|
||
|
||
这次源码交付没有代替现场执行上述停止、更新、编译或启动操作。旧影子进程即使还在显示心跳，也不会自动获得修复。
|
||
|
||
## 后续评价与回退
|
||
|
||
下一轮需要分别统计新运行内的 `DEFERRED_MATCH`、`DEFERRED_DIFFERENCE`、`DEFERRED_UNAVAILABLE`，并按任务阶段及 predictionCycleId 检查独立样本，不能把全部观察周期作为通过次数。导出配对时同时包含观测周期和其引用的预测周期；原始输入继续通过本机 `/shadow/inputs/<cycle_id>` 获取并验证哈希。
|
||
|
||
如果触发证据存储/事务保护，先保留现场错误和运行信息，只停止影子程序。需要回退时，使用保留的旧源码目录或单独检出的 `af8b5f1`；保留新影子证据，不删除或重建数据库，不对现场工作目录执行强制 reset。旧版本分析工具不认识新分类时，应使用新版本导出器解读新运行记录。
|
||
|
||
仍然缺少的正式接管依据：现场确认的安全等待/避让点、拥堵与长期 HOLD 的业务处置验证、特殊交接阶段状态机证据，以及本次更新后的连续运行配对数据。`NO_SAFE_YIELD_POINT` 没有被隐藏或强行改为放行。
|
||
|
||
## 本地验证
|
||
|
||
先用失败测试复现超时永久停采与缺失延迟比较，再验证修复。测试涵盖已结束读取恢复、不可取消读取仍停采、回滚失败、发布耗时预算、提交后登记预测、前后事务重放、车辆和阶段变化、旧路径不适用、缺口与地图变化、重复队列、SQL 证据存储兼容性。
|
||
|
||
现场回放只使用 Git 外的审计输入，不连接生产数据库。2026-09-09 的 11 份输入是独立样本，不伪造连续轨迹、历史交通状态或历史配对结果。测试使用与现场一致的 `ShadowVehicleAssignmentPolicy` 绑定车辆限制。
|
||
|
||
最终验证命令：
|
||
|
||
```text
|
||
mvn -o -pl ruoyi-wcs-shadow -am -Dshadow.replay.audit-directory=<20260908审计目录> -Dshadow.replay.current-directory=<20260909审计目录> test
|
||
```
|
||
|
||
没有私有审计文件的现场运行普通 `mvn -o -pl ruoyi-wcs-shadow -am test` 即可；外部样本回放会明确跳过，不能声称现场也执行了这些回放。
|
||
|
||
2026-09-09 本地最终结果：`BUILD SUCCESS`；共 332 项，331 项通过、0 失败、0 错误、1 项因旧 300 条归档文件缺失跳过。WCS 核心 128 项、协议 10 项、影子模块 194 项（含上述 1 项跳过）。9 月 8 日回放 25 条记录、17 份不同输入；9 月 9 日回放 11 份独立输入，得到 8 个授予、5 个保持、16 个观察结果，原始哈希全部保持。这些是空交通状态下的独立回归结果，不是现场历史调度重建或正式接管验收成绩。
|