FT546-WCS/docs/superpowers/specs/2026-08-06-javaTest-dispatch-completion-audit-design.md

javaTest 调度闭环完成审计设计

日期： 2026-08-06
状态： 已确认并进入执行
范围： javaTest 历史负载驱动中心调度仿真、路线质量和可视化验收

1. 目标

在现有真实历史任务全链路仿真的基础上，补齐上线前最关键的可证明边界：

1. create_date 未来任务不能提前进入调度，优先级排序仍受饥饿保护影响。
2. 已选路线必须是权威地图上的连续合法路径，公开质量评价接口不能接受非法候选。
3. 活动任务的反向剩余路线必须被识别为对向风险，且优先级高于一般路线重合。
4. 已知地图但无路可达的历史任务必须以明确 FAILED/NO_ROUTE 结束并进入报告。
5. 第三次同一交通 HOLD 的集成重规划、预约失败回滚和移动后防抖必须有可复现证据。
6. 240 条真实历史任务仍然全部经过中心重新选车、重新规划、交通裁决、PLC/ACK、逐节点移动、资源释放、归档和幂等 WMS 回调。

2. 保留的业务语义

• task_no、任务类型、物理起点、物理终点和优先级是业务输入。
• create_date 只控制任务到达顺序，并按 10x/100x 加速；不截断真实相邻时间差。
• 历史 agv_id 只做对照；历史 path_info 只做权威地图上的公平比较，不进入新算法输入。
• 历史完成状态和 finish_date 不推进仿真；仿真完成只由 PLC/ACK 和逐节点移动产生。
• 车辆资格和中心选车规则保持现有 VehicleAssignmentService 作为权威策略。
• 路线质量只使用固定字典序元组，不使用受故障影响的耗时。

3. 技术设计

3.1 路线质量输入边界

RouteQualityEvaluator 在计算前校验候选路径的每个站点存在、每条相邻边存在且候选距离与权威地图坐标距离一致。非法候选直接抛出 IllegalArgumentException，防止调用方绕过 RouteCandidatePlanner 把任意节点序列参与排序。

活动路线的相邻有向边与候选边方向相反时，计入 oppositeDirectionConflictCount；同方向或仅物理边重合仍计入 activeRouteOverlapEdgeCount。已计入对向风险的边不再重复计入不兼容边预约。

3.2 调度端到端证据

在 HistoricalDispatchSimulatorTest 中增加小型权威地图夹具：

• 一个未来到达的高优先级任务和一个已到达的低优先级任务，验证未来任务不在其 create_date 前产生 ASSIGN，到达后按有效优先级选择。
• 一个已知但被永久阻断的目标，验证结果为 FAILED、原因 NO_ROUTE，并且没有 ASSIGN 或 COMPLETE。
• 一个相同交通 HOLD 连续三次的活动冲突，验证 REROUTE_TRIGGER、严格更优路线、原子替换失败时旧路线保持不变，以及成功换路后移动前不再次换路。

这些测试不改变真实历史数据，只补足真实回放无法自然覆盖的可控边界。

3.3 报告与浏览器

现有 JSON/CSV/API/HTML 继续消费 Java 产生的 plannedPath、候选、质量、事件和不变量证据。新增测试只验证这些字段在上述边界下不会丢失；浏览器继续显示完整地图、历史参考、当前规划、接近路径、MOVE/HOLD 和重规划前后路线。

4. 风险与降级

• 临时资源冲突仍然进入 HOLD，不转换为 NO_ROUTE。
• 无严格更优路线或原子预约替换失败时保留旧路线和旧资源。
• PLC 失败、断线、重启、低电量和车辆故障不进入交通 HOLD 计数。
• 真实 240 条回放若出现等待或失败，必须保留明确原因，不能用历史完成状态补齐。
• 本设计仍是离线内存仿真，不构成生产 SQL Server、PLC、WMS、HIL 或 ACTIVE 证据。

5. 验收门禁

1. Maven 全量测试失败、错误、跳过均为 0。
2. 240 条历史任务的完成、等待、失败之和等于 240；默认真实负载全部完成。
3. 每个路线阶段候选唯一选中，选中距离不超过最短距离 110%。
4. 节点双占、边容量、对向换边和死锁均为 0。
5. 归档数等于完成数，重复 WMS 投递不产生重复业务效果。
6. 浏览器桌面和移动 QA 通过，完整地图与路径图层开关不改变权威拓扑。