FT546-WCS/docs/runbooks/ft546-shadow-20260910-source-recovery.md

2026-09-10 影子采集恢复修复

修复目标与现场事实

本次只修复影子模块的采集恢复及故障留证。新算法的分车、路径、等待时机可以与正式 WCS 不同，不以逐条一致或差异为零作为正常采集、算法可用或正式接管的门槛。

更新前影子源码为 4408958，buildId 为 ft546-shadow-20260909-observed-traffic-v1。现场 runId 27ff7d71-7074-4b6b-b5ac-de92c048e5ad 的最后成功采集时间为北京时间 2026-09-10 10:10:11；状态为 DEGRADED、collectionStopped=true、SOURCE_TRANSACTION_FAILED，心跳仍在更新。该次总耗时约 7750 ms，没有超过 10000 ms 周期上限。旧版本未持久化异常子类型，不能确定本次究竟发生在获取连接、提交还是回滚阶段。

已通过故障注入确认的代码问题是：获取连接失败与明确已关闭连接的事务完成失败，原先都归为不可恢复的事务错误；另外，首次读取地图后提交失败会留下未成功事务的地图缓存。

行为变化

• 获取连接失败标为 SOURCE_CONNECTION_UNAVAILABLE，按 1、2、4、8、30 秒退避，成功后重置退避。
• 只读事务提交或回滚失败时，只有当前连接明确 isClosed()==true 才标为 SOURCE_CONNECTION_LOST，完成本地清理后重读完整批次。失败批次不进入证据事务。
• 连接仍打开、无法取得连接状态或检查状态本身失败时，继续按 SOURCE_TRANSACTION_FAILED 停采。不可取消的读取和证据存储故障的原有保护不变。
• 地图缓存只在来源事务成功返回后发布，失败事务不会污染后续读取。
• /shadow/status 和心跳增加 lastCollectionFailure，记录有界的异常类型、SQLState、错误码和首个栈位置；不记录原始异常消息、SQL 或连接字符串。恢复后保留上次失败诊断，当前状态仍正常更新。
• 影子 profile 默认记录 log/ft546-shadow.log，10 MB 滚动、归档总量上限 50 MB、最多保留 5 天。现有完整异常日志可能包含异常消息，分享日志前仍需检查敏感内容。

新 buildId：ft546-shadow-20260910-source-recovery-v1。

不需要 SQL 迁移，不更改生产库的数据、表、视图或权限，不更改正式 WCS 调度及 PLC/WMS 通信。来源连接继续使用现场只读账户、原有限时和行数上限。

本地验证

在 optimize/wcs 工作树运行影子模块及依赖模块的离线测试，并加载已保存的现场输入：

mvn -o -pl ruoyi-wcs-shadow -am -Dshadow.replay.current-directory=D:/workSpace/PROJECT_SPACE/FT546/outputs/wcs-shadow-review-20260909 -Dshadow.replay.occupancy-directory=D:/workSpace/PROJECT_SPACE/FT546/outputs/wcs-shadow-review-20260909/post-update-inputs test

结果：BUILD SUCCESS，总计 355 项，353 项通过，2 项因未提供另一组旧归档输入而跳过，0 失败、0 错误。包括连接获取失败恢复、提交/回滚的关闭/打开/未知三态、重试重置、失败批次隔离、地图缓存发布时机，以及诊断留存及脱敏。

11 份当前现场输入和 50 份占用输入的回放通过；这证明已有回归断言成立，不等于任务已由影子算法完成。历史资源账本未重建，不能用这些回放中的 GRANTED/HOLD 数量直接推导现场完成率。

详细测试输出：工作区 outputs/shadow-source-recovery-full-tests.log。本地测试使用 Java 17；现场需使用 Java 8 编译生产源码。测试 H2 依赖需要较新 Java，不要求现场用 Java 8 执行该测试集。

现场交付与启动后验收

维护目标仅为 C:\project\FT546-WCS-SHANDOW 中的 Ft546ShadowApplication。更新前核实影子主类、端口和停止采集状态，保留现场 IDEA 配置及其他已有工作区修改。正式 WCS 不停机。现场采用 Java 8、Maven 3.6.0 和现有离线依赖库编译；完成后由操作人员在 IDEA 启动影子主类。

独立只读采集探针只验证当前连接、新采集器、完整批次及输入校验，不启动完整影子调度，不写入任一数据库。其成功不能替代重启后实际证据落库和持续运行检查。

启动后确认：

1. buildId 为本次版本，13 项启动检查全部 PASS，collectionStopped=false。
2. 间隔多个采集周期观察 lastCompletedCycle 持续推进、evidenceBacklog 不积压，新的完整输入及哈希、周期证据持续落库。
3. 发生短时连接故障后能恢复，诊断能解释故障；无法确认事务安全结束的故障仍需排查。
4. 分别评估输入完整性、路线和资源安全、可达性、等待解除和长期饥饿。新旧算法结果差异用于解释行为，不能直接当作算法错误；SOURCE_GAP 也可能是正式 WCS 尚未生成相应 path_info，需结合原始输入解释。

本次是恢复影子测试的数据采集，不是允许新算法接管正式调度。持续采集与有限快照回放不能单独证明新算法完成了现场任务。