# javaTest 有界绕行与冲突感知路径规划设计

**日期：** 2026-08-06  
**状态：** 已完成方案讨论，等待书面确认  
**适用范围：** `javaTest` 历史任务中心调度仿真与调度路径审计页面

## 1. 背景

当前 `javaTest` 使用 `GridPathPlanner` 在完整地图上执行 BFS，得到边数最少且结果确定的路径。
历史 `path_info` 只用于结果对照，不参与重新规划。240 条历史任务的初步结果为 137 条路径序列
发生变化，但该数字不能直接证明路径优化有效：

- 130 条历史路径的首尾与解析后的物理业务端点不一致；
- 2 条历史路径含未知或非邻接段；
- 剩余 108 条可公平比较的任务中，103 条完全相同，4 条路线不同但边数相同，只有 1 条更短；
- 可比较任务的平均边数仅从 10.14 降到 10.12。

因此，本设计不再用“路径是否不同”或受故障影响的实际完成时间证明优化效果，而是在最短物理
距离附近选择交通冲突更少、路线重叠更少、转弯更少的候选路线，并提供完整、可解释的决策证据。

## 2. 目标与非目标

### 2.1 目标

1. 接近路径和服务路径都允许在最短物理距离 110% 范围内绕行。
2. 只使用当前活动任务、节点占用、边预约和走廊方向判断交通风险，不使用历史热度。
3. 按固定业务优先级比较候选路线，不使用难以解释和调参的加权总分。
4. 同一交通资源连续造成 3 个调度周期 HOLD 后，从车辆当前位置重新规划剩余路线。
5. 路线切换必须保持当前占用和预约安全，不能因重规划产生资源空窗。
6. 将路线质量、交通执行和故障恢复分开统计。
7. 相同地图、输入和交通快照必须产生相同结果。

### 2.2 非目标

1. 不用实际行驶时间或最终任务完成时间给路径质量打分。
2. 不使用历史 `path_info` 约束新路线。
3. 不在本次改造中改变现有车辆资格、低电量和车辆选择业务规则。
4. 不把 PLC 失败、断线、低电量或车辆故障当成交通 HOLD。
5. 不接入生产数据库、真实 PLC、真实 WMS 或实时交通服务。

## 3. 业务术语

- **接近路径：** 重新选中的车辆当前位置到任务物理起点 A 的路线。
- **服务路径：** 任务物理起点 A 到物理终点 B 的路线。
- **基准最短距离 D：** 在永久禁行条件下，起终点间可达路线的最小坐标距离。
- **有界候选路线：** 物理距离不超过 `D * 1.10` 的无环路线。
- **交通快照：** 某次调度决策时的车辆占用节点、边预约、走廊方向和其他活动路线。
- **交通 HOLD：** 下一步因节点、边、对向或走廊方向冲突而暂时不能安全推进。
- **相同阻塞：** 任务、车辆、阻塞资源标识和交通 HOLD 原因均相同。

## 4. 总体架构

### 4.1 `RouteCandidatePlanner`

职责：根据完整 `GridMap`、起点、终点和永久禁行资源生成确定性的有界候选路线。

输入：

- `GridMap`
- 起点、终点
- 永久禁行节点或边
- `RoutePlanningPolicy`

输出：

- 基准最短距离
- 最短路线
- 不超过 110% 的候选路线
- 是否命中候选数量上限

该模块不读取车辆状态、交通预约、历史路径或任务优先级，只负责生成地图上合法的路线候选。

### 4.2 `RouteQualityEvaluator`

职责：使用同一时刻的 `TrafficRouteSnapshot` 对候选路线进行可解释的业务排序。

输入：候选路线、交通快照、当前任务和车辆。  
输出：每条路线的 `RouteQuality` 以及最终 `RoutePlanDecision`。

### 4.3 `TrafficRouteSnapshot`

职责：为一次规划决策提供不可变交通证据，避免候选路线使用不同时间点的数据。

包含：

- 车辆当前占用节点及归属车辆；
- 已预约的有向边、方向和归属任务；
- 走廊方向预约及归属任务；
- 其他活动任务尚未完成的剩余路线；
- 当前任务和车辆自身已经合法持有的资源。

### 4.4 `HoldReroutePolicy`

职责：只累计交通 HOLD，并在同一阻塞连续出现 3 个调度周期时触发重规划。

### 4.5 `RouteDecisionEvidence`

职责：保存候选生成、路线评分、HOLD 触发、资源替换和最终选择的可审计证据，供 JSON 报告和
HTML 页面展示。

## 5. 物理距离与候选路线

### 5.1 边距离

当前完整地图共有 8 层、1239 条边，不存在跨层边。相邻站点边距离按地图坐标的欧氏距离计算：

```text
edgeDistance = sqrt((to.x - from.x)^2 + (to.y - from.y)^2)
pathDistance = sum(edgeDistance)
```

距离单位是地图坐标单位，不宣称为米。未来如增加跨层边，必须由地图元数据显式提供该边距离；
不得根据楼层编号虚构垂直距离。

### 5.2 候选生成算法

采用确定性的 K 最短无环路径方案：

1. 使用 Dijkstra 计算基准最短路线和距离 `D`；
2. 按距离从小到大生成无环候选路线；
3. 下一候选距离超过 `D * 1.10` 时停止；
4. 最多保留 32 条候选；
5. 距离相同时按完整站点序列排序；
6. 未知节点、永久封闭道路和静态禁行资源不进入候选；
7. 当前临时占用和预约不从地图删除，只在质量评价阶段计入风险。

候选上限 32 是性能边界，不是业务评分。达到上限时在证据中写入
`candidateLimitReached=true`，但仍从已生成候选中作出确定性选择。

### 5.3 接近路径与服务路径

现有 `VehicleAssignmentService` 继续负责车辆资格和选车，不在本设计中改变选车规则。选车完成后：

1. 为选中车辆计算“当前位置到任务起点”的有界接近路径；
2. 独立计算“任务起点到任务终点”的有界服务路径；
3. 分别保存两段路线的最短距离、候选数量和选择原因；
4. 交通预约仍对拼接后的完整执行路线申请。

这样可以优化两段路线，同时避免本次改造无意改变已经验证过的自动选车行为。

## 6. 路线质量排序

每条候选路线生成以下固定顺序的比较元组：

```text
(
  oppositeDirectionConflictCount,
  occupiedNodeCount,
  incompatibleReservedEdgeCount,
  activeRouteOverlapEdgeCount,
  turnCount,
  physicalDistance,
  canonicalPath
)
```

排序为字典序，前一项不同时不再比较后一项。

### 6.1 指标定义

- `oppositeDirectionConflictCount`：候选有向边与其他任务已预约方向相反的数量。
- `occupiedNodeCount`：候选未来节点中被其他车辆占用或独占预约的数量；当前车辆自身起点不计。
- `incompatibleReservedEdgeCount`：候选边与现有容量或方向规则不兼容的预约数量；已计为对向冲突
  的边不重复计数。
- `activeRouteOverlapEdgeCount`：候选无向边与其他活动任务剩余路线重合的数量；这是未来竞争风险，
  不等同于已经发生的资源冲突。
- `turnCount`：相邻两条同层边的方向向量发生变化的次数。
- `physicalDistance`：第 5 节定义的坐标距离。
- `canonicalPath`：用完整站点序列作最终稳定决胜。

安全规则仍由交通资源裁决执行。质量评价只决定优先尝试哪条路线，不能绕过节点容量、边方向或
走廊预约。

## 7. HOLD 后重规划

### 7.1 触发条件

仅以下原因进入连续 HOLD 计数：

- 下一节点被其他车辆占用或独占预约；
- 下一条边不可申请；
- 存在对向换边风险；
- 走廊方向预约冲突。

键为：

```text
(simulationTaskId, vehicleId, blockingResourceId, holdReason)
```

连续第 1、2 次只保持 HOLD；连续第 3 次产生 `REROUTE_TRIGGER`。车辆发生移动、阻塞资源或原因
改变、HOLD 消失、车辆被重新分配时清零。

PLC 发送失败或未 ACK、低电量、车辆故障和断线不进入该计数。

### 7.2 重规划范围

- 尚未到达任务起点：重新计算“当前位置到起点”的接近路径，同时基于同一交通快照重新评价
  “起点到终点”的服务路径。
- 已进入服务路径：只计算“当前位置到任务终点”的剩余服务路径。

### 7.3 防止路线抖动

满足以下条件才允许切换：

1. 新剩余路线与当前剩余路线不同；
2. 新路线不超过对应最短距离 110%；
3. 新路线的质量元组严格优于当前路线；
4. 新路线的路线级走廊预约能够安全替换；
5. 上次成功换路后车辆已经至少移动一个节点，或当前路线出现永久失效。

找不到严格更优路线时产生 `REROUTE_REJECTED` 并继续 HOLD，不关闭任务。

## 8. 预约替换与资源释放

新增原子语义的路线级走廊预约替换操作：

```text
保留车辆当前占用节点和已进入边
→ 以当前任务旧预约为可替换资源，试算新剩余路线的走廊方向
→ 在不暴露中间状态的前提下提交走廊预约替换
→ 成功后提交新 remainingPath
→ 释放旧路线不再使用的走廊预约
```

如果试算或替换失败，旧路线和现有合法资源保持不变。不得先释放旧预约再申请新路线。

节点和边不因重规划而整条路线预占，仍由现有交通控制器在车辆移动前逐段申请，并在车辆通过后
逐段释放。重规划不能释放车辆当前节点、正在通过的边或其他任务资源。该边界既保留现有安全
语义，也避免因整条路线预占扩大资源等待和死锁风险。

## 9. 失败与降级规则

- 完整地图永久不可达：任务关闭为 `NO_ROUTE`。
- 存在地图路线但所有候选都有临时冲突：选择风险最小候选，交给交通裁决决定 GRANT/HOLD。
- 候选达到 32 条上限：从已有候选选择并记录上限证据。
- HOLD 后无更优路线：保持当前路线和 HOLD。
- PLC 失败或未 ACK：沿用原有协议重试，不触发路径重规划。
- 车辆故障或断线：沿用重新选车流程；新车辆确定后重新规划接近路径和服务路径。
- 低电量：车辆不再接收新任务；不把低电量伪装成交通冲突。

## 10. 事件与审计证据

保留现有事件，并新增：

- `REROUTE_TRIGGER`：包含连续 HOLD 次数、阻塞资源和原因；
- `REROUTE`：包含旧剩余路线、新剩余路线、两者质量元组和选择原因；
- `REROUTE_REJECTED`：包含没有更优候选、超出 110% 或预约替换失败原因。

每次初始规划和重规划输出：

- `shortestPhysicalDistance`
- `selectedPhysicalDistance`
- `detourRatio`
- `candidateCount`
- `candidateLimitReached`
- 质量元组各项指标
- `decisionReason`
- `pathVersion`
- `planningStage`：`APPROACH` 或 `SERVICE`

浏览器继续显示完整地图、历史路径、新规划路径和实际轨迹，并在检查器中分别显示接近路径和
服务路径的选择证据。实际时间、完成时间和 PLC 重试放在“运行与故障恢复”区域，不进入路线评分。

## 11. 历史路线比较口径

每条历史任务先分类：

- `COMPARABLE`：历史路径首尾与物理业务端点一致，且所有连续边都存在于权威地图；
- `ENDPOINT_MISMATCH`：历史首尾与物理业务端点不一致；
- `INVALID_HISTORY_PATH`：包含未知节点或非邻接段。

只有 `COMPARABLE` 任务进入路线质量统计。统计分类为：

- 完全相同；
- 物理距离更短；
- 距离相同但冲突或转弯更少；
- 距离在 110% 内略长但冲突更少；
- 新路线质量更差。

`pathChanged` 继续保留节点序列语义以兼容现有报告，但不能再单独作为“优化成功”指标。

## 12. 验收门禁

### 12.1 路线算法门禁

1. 所有选中路线距离不超过对应最短物理距离 110%。
2. 最终路线必须是已生成候选中的字典序最优质量元组。
3. 临时冲突不能导致错误的 `NO_ROUTE`。
4. 同一输入、地图和交通快照重复运行必须得到相同路线和原因。
5. 历史端点不一致或存在无效段时不得计入优化比例。

### 12.2 HOLD 与资源门禁

1. 同一交通冲突连续 1、2 次不重规划，第 3 次触发。
2. PLC 失败、低电量、故障和断线不能误触发交通重规划。
3. 找不到严格更优路线时保持原路线。
4. 路线切换失败不能丢失旧预约。
5. 车辆移动前后节点、边和走廊资源均保持单一合法归属。
6. 节点双占、资源超容量、对向换边和死锁为 0。

### 12.3 业务闭环门禁

1. 基准 240 条历史任务全部进入终态，不遗留活动或等待任务。
2. 所有完成任务归档一次且仅一次。
3. WMS 重复投递不产生重复业务效果。
4. 失败任务必须有明确、可审计的失败原因。

## 13. 测试策略

### 13.1 单元测试

- 坐标距离和路线距离；
- 110% 边界内外候选过滤；
- 无环候选和 32 条数量上限；
- 固定质量元组排序；
- 转弯、重叠、占用和对向冲突计数；
- 相同输入的确定性；
- 历史路线三类可比性判定。

### 13.2 集成测试

- 最短路线有冲突，10% 内存在无冲突绕行，必须选择绕行；
- 无冲突绕行超过 10%，必须保留允许范围内的最优路线；
- 所有候选有临时冲突时保持可调度而非 `NO_ROUTE`；
- 连续第 3 次相同交通 HOLD 重规划；
- 阻塞资源变化后计数重新开始；
- 成功换路后移动一个节点前不再次普通重规划；
- 新预约失败时旧预约保持完整；
- PLC 重试和车辆故障不污染交通 HOLD 计数。

### 13.3 历史负载和浏览器验收

- 重新执行 240 条历史任务并输出 `COMPARABLE/ENDPOINT_MISMATCH/INVALID_HISTORY_PATH`；
- 报告接近路径和服务路径的候选、质量、绕行比例和重规划证据；
- 在完整地图中显示初始路线、HOLD 点和重规划后的剩余路线；
- 验证所有路线切换均能从事件和资源证据追溯；
- 验证归档、WMS 幂等和所有安全门禁。

## 14. 性能与兼容性

- 不新增生产依赖，保持 Java 8 编译目标。
- 候选数量固定上限为 32，避免历史批量回放搜索量失控。
- 现有 `plannedPath`、`pathChanged` 和历史证据字段保持兼容；新增字段只扩展 JSON。
- 当前 BFS 行为保留为基准测试和最短边数对照，不再承担最终冲突感知选路职责。
- 本设计只修改 `javaTest`，不直接替换生产 WCS 调度实现。