5.5 KiB
FT546 影子程序：2026-09-14 证据提交超时修复
适用版本与范围
- 分支：
optimize/wcs - 修复前源码：
0d53f41 - 新 buildId：
ft546-shadow-20260914-commit-recovery-v1 - 修改范围：
ruoyi-wcs-shadow。正式 WCS 调度、PLC/WMS 通信及生产数据库不作改动。 - 无 SQL 迁移，无需清空影子库或更换 IDEA 连接配置；仍按现场源码方式编译启动。
本版本用于恢复持续影子采集，不代表批准新调度算法接管正式设备。
故障证据
9 月 14 日检查的旧 runId 为 10ec02d4-5a64-4ea9-bfc4-6f03eca5089c。
最后成功周期为北京时间 9 月 11 日 02:31:03.399，此后心跳继续更新，采集却保持停止。
超时诊断记录周期 10001 ms，其中前置心跳 4782 ms、来源读取 48 ms、证据提交 5154 ms；
工作线程当时位于 SQL Server JDBC 的提交/套接字读取路径。复查线程栈时，该工作线程已经空闲。
旧实现一旦超过周期看门狗预算，就取消 Future 并永久停采，即使原事务后来正常结束，也无法确认并恢复。 现有证据不能确定数据库延迟由磁盘、锁、网络中的哪一项造成；本次修复不将这些推测当作已确认根因。
修复后的行为
- 保留首次采集前的心跳检查。之后正常周期仅在完成后写一次心跳，减少证据库写入和前置耗时。
- 保留 10 秒周期预算。若超时发生在
TRANSACTION_COMMIT或RECORDING，保留原 Future，进入等待确认状态，不启动新批次、不重放旧事务，也不取消正在提交的 JDBC 调用。 - 后续调度检查原任务的终态。只有正常结束，包括事务清理及提交后回调完成，才确认迟到成功、推进原批次游标，并允许下一批采集；跨延迟区间的待比较数据会失效。
- 提交失败、确认丢失或等待期间心跳写入失败时仍停止采集。原任务持续未结束且等待超过 30 秒时，以
SHADOW_COMMIT_COMPLETION_UNCONFIRMED停采。窗口按调度轮询检查，同时采用单调时间与墙上时间，避免时钟回拨导致无限等待。 - 超过等待窗口后，不再调度新批次，但原数据库事务仍可能随后提交。停止采集不等于已回滚，不能据此盲目重放原事务。
- 非提交阶段超时继续采用原有停止保护。人工关闭后，即使旧提交迟到完成，也不能将状态恢复为 READY。
仅影子证据 SQL Server 连接增加 socketTimeout=15000 毫秒及 cancelQueryTimeout=1 秒。
现有语句超时 3 秒、连接池大小 2、连接获取等待 2 秒保持不变，来源只读连接配置保持不变。
这些超时限制单次驱动等待，不保证整个周期或 JDBC 清理严格在 15 秒内返回。
如何判断是否仍在采集
在服务器浏览器打开 http://127.0.0.1:18091/shadow/status：
- 正常：
status=READY、collectionStopped=false、awaitingCommitCompletion=false；重复查看时lastCompletedCycle应持续推进。 - 等待迟到提交：
awaitingCommitCompletion=true，原因SHADOW_COMMIT_AWAITING_COMPLETION。此时不启动新采集。 - 停止采集：
collectionStopped=true。进程存活或心跳时间更新不能作为持续采集的依据。 lastCollectionFailure保留证据事务异常及可提取的 SQLState 等诊断；恢复后历史失败记录仍可能存在，应结合当前状态与时间判断。
迟到成功时日志包含 late commit confirmed。永久停采后每分钟输出一次 collection remains stopped 提醒。
本地验证
- 完整回归：核心 131 项、协议 10 项、影子 221 项，共 362 项；360 项通过，2 项因缺少另一组历史归档输入跳过，0 失败、0 错误。
- 当前 11 份及占用场景 50 份现场输入回放通过。
- 完整回归后补充了重复诊断快照的计时测试，单独运行该测试类 3 项全部通过；该补充之后未修改生产代码。
- 使用真实 H2 事务注入提交延迟，验证迟到成功只提交一次、随后新批次继续、失败/确认丢失不重放、等待超限保护、关闭后不复活及心跳失败保护。
- 使用 SQL Server JDBC 9.2.1.jre8 的属性解析验证有效超时配置，包括 URL 中无限等待值被覆盖的情形；此项未连接实际 SQL Server。
- Java 8
1.8.0_152、Maven3.6.0，离线执行影子模块及其依赖的clean compile，结果BUILD SUCCESS。 - 独立代码核验未发现阻止交付的问题，
git diff --check通过。
本地事务故障注入不等同于真实 SQL Server 网络故障试验。长期数据库抖动下的表现仍需重新采集现场运行记录。
现场更新与启动核对
现场影子源码目录为 C:\project\FT546-WCS-SHANDOW。更新前重新核实该目录版本、影子主类及 18091 监听进程，
只停止确认属于影子程序的旧进程。保留现场 .gitignore、IDEA 配置、opencode.json 与 shadow-evidence。
将影子分支快进到本次修复提交，使用现场 Java 8、Maven 3.6.0 及现有离线依赖库编译。
核实新 buildId、Java class 主版本 52、正式 WCS/WMS 进程仍在运行，再由用户在 IDEA 启动 Ft546ShadowApplication。
本说明描述更新流程，不单独证明现场已更新；以本次现场操作记录为准。
启动后确认新的 runId/buildId、全部启动检查 PASS，以及多个采集周期持续落库。 后续上线评估按安全性、有效任务覆盖、载货运输及任务完成能力检查；新旧调度逐条一致不是验收门槛。