docs: design real history driven dispatch simulation

docs/superpowers/specs/2026-07-31-wcs-real-history-driven-dispatch-simulation-design.md

@@ -0,0 +1,95 @@
+# WCS 真实历史负载驱动全链路调度仿真设计
+
+## 1. 目标
+
+把 `FT546-wcs.dbo.wcs_srgv_queue_finish` 固化的 240 条真实任务作为业务负载输入，验证调度中心从任务到达、重新选车、重新规划路径、交通裁决、模拟协议下发、逐段移动、资源释放到完成归档的完整功能。历史车辆号、历史路径和历史完成时间只作为对照，不控制仿真结果。
+
+本测试是纯内存全链路仿真，不连接数据库、PLC 或 WMS，不修改 `ruoyi-*` 生产模块，不宣称现场 SHADOW、HIL 或生产可用性。
+
+## 2. 方案比较
+
+### 方案 A：继续固定历史车辆和路径
+
+实现简单，但只能检查历史记录之间的路径交集，不能验证重新选车、路径规划和队列执行，不满足目标。
+
+### 方案 B：仅把历史任务送入 LEGACY Demo
+
+可以覆盖选车、BFS路径、模拟发送和归档，但不会经过新增 SHADOW 资源账本和滚动交通裁决，不能完整验证中央交通控制。
+
+### 方案 C：历史负载驱动组合仿真（采用）
+
+复用 `VehicleAssignmentService`、`GridPathPlanner`、`ShadowTrafficCoordinator`、`RollingDispatchPolicy` 和 `ResourceLedger`，增加独立仿真编排层。它既覆盖业务调度链，又经过当前交通安全内核，且保持生产代码零修改。
+
+## 3. 输入口径
+
+- 使用已固化并经 SHA-256 校验的 240 条真实历史记录。
+- 每条数据库行都是独立任务，唯一仿真 ID 为 `task_no@guid`；相同任务号的多阶段记录不合并。
+- `create_date` 决定任务到达顺序；相同时间同时到达，时间间隔压缩为仿真 tick，不模拟数月空闲时间。
+- `task_type`：`1→INBOUND`、`2→OUTBOUND`、`3→RELOCATION`。
+- `priority` 作为业务优先级；缺失时使用最低优先级。
+- 历史 `agv_id` 只用于报告对照，调度中心必须重新选车。
+- 历史 `path_info` 的相邻节点用于构建测试拓扑；规划器在拓扑上重新计算路线，不直接返回历史路径。
+- 因业务端点 `tsj` 可能不是物理地图节点，物理起终点使用历史路径的首末有效节点；原始 `start_site/end_site` 仍完整保留在报告。
+- 未知地图节点或无法形成物理端点的记录按 `INPUT_REJECTED` 失效关闭，不制造路径。
+
+## 4. 仿真地图与车辆
+
+从 240 条路径的全部有效相邻节点构造无向拓扑，并使用 `map-sites.json` 的 `x/y/z` 作为选车距离和楼层。所有节点及无向边容量均为 1；未签字的冲突区、提升机容量和安全 YIELD 点不自动推断。
+
+车辆集合固定为真实样本中的 `1/2/3`。每辆车初始位置取该车最早有效记录的物理起点，状态为在线、自动、空闲、允许下发、电量 100。每辆车始终占用当前节点；移动时只申请“当前节点＋下一条无向边＋下一节点”的滚动资源包。
+
+## 5. 每个仿真 tick
+
+1. 注入本 tick 到达的真实任务。
+2. 对空闲车辆和待调度任务调用现有选车规则；历史车辆号不参与约束。
+3. 使用拓扑 BFS 规划“车辆当前位置→物理起点→物理终点”。无可达路线记录 `NO_ROUTE`。
+4. 为每个活动车辆构造不可变 `TrafficVehicleSnapshot` 和 `TrafficSnapshot`。
+5. 为下一段移动构造 `ShadowCandidate`，调用 `ShadowTrafficCoordinator.run`。
+6. `GRANT` 时把段资源写入内存权威账本；`HOLD/YIELD` 时保留任务等待并记录原因。
+7. 模拟协议下发和 ACK。固定、可重复的故障计划使部分首次发送失败，下一 tick 重试。
+8. ACK 成功后车辆前进一个节点，释放旧节点和已通过边，保留新节点。
+9. 到达终点后完成并归档；模拟完成接收器按任务 ID 去重，禁止重复完成通知。
+10. 每 tick 检查资源容量、车辆唯一活动任务、完成幂等和确定性不变量。
+
+## 6. 终止与失效关闭
+
+- 全部任务完成、明确拒绝或 `NO_ROUTE` 后正常结束。
+- 连续 500 tick 无任务完成或车辆移动时标记 `DEADLOCK_TIMEOUT` 并失败。
+- 总 tick 上限为 20,000；超过上限测试失败。
+- 未知资源、地图版本错配、陈旧快照、资源超容量或重复完成通知立即使测试失败。
+- 不使用历史 `finish_date` 强制完成；它只用于历史耗时对照。
+
+## 7. 验收指标
+
+必须满足：
+
+- 输入记录数 240，且原始任务号、GUID、历史车辆和业务端点可回查。
+- 每条输入恰有一个终态：`COMPLETED`、`INPUT_REJECTED` 或 `NO_ROUTE`。
+- 资源超容量、同点双占、对向边同时占用、重复完成通知均为 0。
+- 至少出现一次调度中心重新选车，证明没有固定使用历史 `agv_id`。
+- 至少出现一次重新规划路线与历史路径不同，证明没有固定返回 `path_info`。
+- 固定故障计划至少触发一次协议失败并成功重试。
+- 相同输入运行两次，逐任务终态、分配车辆、规划路径、HOLD次数和完成顺序完全一致。
+- 现有 60 条人工安全场景和全部 Maven 测试继续通过。
+
+完成率作为功能测试结果报告，不预先伪造必须 100%；如果出现 `INPUT_REJECTED` 或 `NO_ROUTE`，报告必须列出原始任务和具体原因。安全指标任一非零则整体失败。
+
+## 8. 输出
+
+生成新的独立目录：
+
+```text
+outputs/wcs-history-driven-dispatch-simulation-<runId>/
+├── summary.json
+├── task-results.csv
+├── tick-events.csv
+├── invariant-results.json
+├── readable-report.xlsx
+└── manifest.sha256
+```
+
+Excel包含“测试总览、任务结果、重新选车、等待与重试、数据问题、来源与边界”六张表。首页必须标注“真实历史负载驱动纯内存仿真，不是现场 SHADOW/HIL/ACTIVE 验收”。
+
+## 9. 明确不能证明的内容
+
+该仿真可以验证纯内存调度功能、确定性和安全不变量，但不能证明真实 SQL 事务、真实 PLC 协议、WMS 回调、网络故障恢复、HIL 或生产可用性。这些仍需按 `docs/WCS算法优化/06-测试灰度与验收.md` 的 L2～L9 分层执行。