docs(javaTest): plan dispatch completion audit

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

@@ -0,0 +1,64 @@
+# 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 通过，完整地图与路径图层开关不改变权威拓扑。