From 4a86a63b7b2f899c1730e89557404f68f31874f3 Mon Sep 17 00:00:00 2001
From: zgw <13623675548@163.com>
Date: Fri, 31 Jul 2026 13:39:00 +0800
Subject: [PATCH] docs: require complete center-planned history simulation

---
 ...plete-center-dispatch-simulation-design.md | 219 ++++++++++++++++++
 ...story-driven-dispatch-simulation-design.md |   4 +
 2 files changed, 223 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-31-wcs-complete-center-dispatch-simulation-design.md

diff --git a/docs/superpowers/specs/2026-07-31-wcs-complete-center-dispatch-simulation-design.md b/docs/superpowers/specs/2026-07-31-wcs-complete-center-dispatch-simulation-design.md
new file mode 100644
index 0000000..8ed5e4b
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-31-wcs-complete-center-dispatch-simulation-design.md
@@ -0,0 +1,219 @@
+# WCS 完整地图中心调度历史任务仿真设计
+
+## 1. 目标与强制结果
+
+把固化的 240 条 `dbo.wcs_srgv_queue_finish` 历史记录只作为任务负载输入，
+由调度中心基于独立完整地图重新选车、重新规划路径并执行全生命周期。
+
+最终真实负载验收必须同时满足：
+
+- 输入 240 条，完成 240 条，等待 0 条，失败 0 条。
+- 每条任务均实际经历到达、排队、选车、寻路、资源裁决、PLC/ACK、逐节点移动、
+  逐段释放、归档和 WMS 完成回调。
+- 节点双占、资源超容量、对向换边、重复归档和重复 WMS 业务效果均为 0。
+- 不能读取历史完成状态直接完成任务，不能把历史 `path_info` 作为地图或规划结果。
+
+这是纯内存确定性仿真，不连接真实 PLC/WMS，不修改 `ruoyi-*` 生产模块，不替代
+SHADOW、HIL 或 ACTIVE 现场验收。
+
+## 2. 方案选择
+
+### 方案 A：继续从历史 `path_info` 生成拓扑
+
+拒绝。`path_info` 是调度中心规划后的历史输出，用它生成地图会形成循环验证，
+无法证明新算法独立规划。
+
+### 方案 B：启动生产 Spring 服务并连接实时数据库
+
+不采用。它更接近现场，但受实时车辆、队列、设备和数据库状态影响，无法生成可重复的
+自动化验收证据，还会扩大测试对生产模块的依赖。
+
+### 方案 C：完整权威地图快照驱动纯内存中心调度
+
+采用。只读固化 `dbo.wcs_srgv_map` 的完整非敏感投影，按生产地图规则构建网格；
+任务与地图完全独立，调度结果可重复，同时仍复用当前中心调度、交通资源账本和协议模拟。
+
+## 3. 权威输入
+
+### 3.1 历史任务快照
+
+沿用已经 SHA-256 校验的 240 条任务记录。字段口径如下：
+
+- `task_no/guid/task_type/start_site/end_site/priority/create_date`：真实业务输入。
+- `agv_id`：历史车辆对照，不参与选车约束。
+- `path_info`：历史规划结果对照，不参与地图、可达性、寻路或交通裁决。
+- `finish_date`：历史耗时对照，不控制仿真结束。
+- 历史完成状态：只说明该任务曾完成，不产生仿真状态迁移。
+
+### 3.2 完整地图快照
+
+新增完整 `dbo.wcs_srgv_map` 快照，至少保留：
+
+```text
+site_id, x, y, z, value, axy, warehouse, space_area
+```
+
+只读核验基线：
+
+- 全表 2,552 个网格单元，覆盖 `x=1..29`、`y=1..11`、`z=1..8`。
+- `value IN (1,2)` 的可通行单元 1,175 个，且都有唯一非空 `site_id`。
+- 240 条样本所在 1～3 层共有 445 个可通行站点。
+- 完整地图及 manifest 均计算 SHA-256，测试运行不再连接数据库。
+
+快照不包含连接串、设备地址、凭据或其他敏感字段。
+
+## 4. 地图编译与端点解析
+
+地图编译遵循生产 `RoadCacheServiceImpl` 与 `PathFinder` 的网格语义：
+
+1. 仅 `value=1/2` 的单元可通行。
+2. 同一层中曼哈顿距离为 1 的可通行单元建立无向边。
+3. 每个节点和边的交通容量为 1。
+4. 站点坐标直接来自地图快照，不从任务历史路径推断。
+5. 地图编译后必须校验站点 ID 唯一、坐标唯一、边端点存在和每层连通分量。
+
+业务端点按生产规则解析：
+
+- 普通站点直接使用 `wcs_srgv_map.site_id`。
+- `tsj` 映射到任务所在层的 `07050{floor}`。
+- 优先使用起点地图层作为任务物理层；历史 `the_floor` 只在业务别名解析时使用并交叉校验。
+- 解析后的物理起终点必须存在且位于同一可达连通分量，否则真实负载验收立即失败，
+  不降级使用 `path_info`。
+
+只读验证已经证明上述规则下 240 条任务的起终点均存在，且不读取 `path_info` 时
+240 对起终点全部可达。
+
+## 5. 中心调度数据流
+
+```text
+create_date 到达事件
+  -> 饥饿保护优先队列
+  -> 健康空闲车辆候选
+  -> 中心选车
+  -> 完整地图重新规划 vehicle->source->target
+  -> 路线/走廊预约
+  -> SHADOW 下一段资源裁决
+  -> 模拟 PLC 发送与 ACK
+  -> 车辆移动一个节点
+  -> 释放旧节点和已通过边
+  -> 到达后唯一归档
+  -> WMS 幂等完成回调
+```
+
+规划器必须在每次初始分配、故障恢复、协议重试耗尽和避让完成后重新计算路径。
+报告保存新规划路径，并在任务结束后才与历史 `path_info` 比较。
+
+## 6. 交通预约与确定性解锁
+
+当前活锁的根因是：一个车辆的剩余路线被空闲车辆占用，其他任务又被整条路线反向冲突
+门禁阻塞。新调度器采用以下规则：
+
+### 6.1 路线预约
+
+- 每个活动任务保存当前规划路径和剩余无向边集合。
+- 路线重叠但方向一致时可以并行准入，具体移动仍由下一段资源账本串行化。
+- 路线存在反向共享边时，按有效优先级、等待年龄、到达时间、任务 ID 决定唯一方向所有者。
+- 方向所有者到达冲突区出口前不可被新任务反向抢占；释放出口后重新裁决。
+
+### 6.2 阻塞车辆迁移
+
+- 若方向所有者的剩余路径被空闲车辆当前位置占用，中心调度生成内部
+  `CLEARANCE_MOVE`，而不是让业务任务无限 HOLD。
+- 清障目标必须是完整地图中的真实可通行节点，且不在方向所有者剩余路径、其他车辆位置
+  或已预约资源中。
+- 目标按最短路径长度、非主干优先、站点 ID 稳定排序选择；迁移本身也经过规划、
+  SHADOW 裁决、PLC/ACK、逐节点移动和资源释放，严禁瞬移。
+- 清障完成后原业务任务重新规划。内部迁移不计入 240 条业务任务完成数，但完整写入事件证据。
+
+### 6.3 进展保证
+
+- 每个冲突连通分量同时只有一个方向所有者。
+- 连续 HOLD 达阈值时保留原到达时间和老化优先级，不把任务放回队尾。
+- 无冲突任务可在其他地图区域继续并行。
+- watchdog 监视“业务终态增加、车辆沿授权路线前进、清障迁移完成”三类有效进展；
+  重复 HOLD 和重复分配不算进展。
+- 真实负载出现 watchdog 或 tick 上限即测试失败，不再作为可接受的 WAITING 报告。
+
+## 7. 优先级与饥饿保护
+
+- 排序键：有效优先级、`create_date`、`task_no`、`guid`、稳定序号。
+- 数值越小优先级越高。
+- 每等待 30 仿真秒提升一级，有效优先级最低提升到 0。
+- 清障迁移继承被保障业务任务的方向所有权，但不能改变业务任务自身优先级。
+- 低优先级任务一旦成为方向所有者，必须获得至少一个可验证移动进展后才允许重新竞争。
+
+## 8. 故障和恢复
+
+模拟 PLC 发送失败、ACK 超时/丢失、断线、PLC 重启、低电量和车辆故障继续使用固定故障计划。
+
+- 故障车辆停止接收新任务并释放未执行的下一段资源。
+- 活动业务任务保留原到达时间后重新调度。
+- 旧 boot ID 的 ACK 拒绝生效。
+- 低电量或故障恢复后车辆重新进入候选池。
+- 故障不能把真实负载任务转为 FAILED；达到重试阈值后必须换车或延后重试。
+- 只有地图快照自身违反结构契约时才允许启动失败，不能把单条真实任务关闭来满足总数。
+
+## 9. 归档与 WMS
+
+- 只有车辆逐节点抵达物理终点才能完成业务任务。
+- 每个任务 ID 只允许一条归档记录。
+- 仿真主动对每个完成任务投递两次 WMS 完成通知，业务接收器只产生一次业务效果。
+- 最终必须满足归档数 240、WMS 投递尝试 480、WMS 业务效果 240。
+
+## 10. TDD 与验收测试
+
+实现必须先添加并运行以下失败测试：
+
+1. 修改同一任务的历史 `path_info` 不改变新规划路径。
+2. 删除 `path_info` 后，只要业务输入和完整地图有效，任务仍能规划和完成。
+3. 完整地图按 `value` 和坐标生成连边，不能使用历史相邻节点生成边。
+4. `tsj` 在 1～3 层正确映射到 `070501/070502/070503`。
+5. 三车走廊阻塞场景生成实际清障移动并最终完成，不出现换边或双占。
+6. 对向路线按优先级和老化确定方向所有者，低优先级最终通行。
+7. 240 条真实任务运行两次均得到完全相同结果。
+
+最终自动验收断言：
+
+```text
+inputCount == 240
+completedCount == 240
+waitingCount == 0
+failedCount == 0
+archiveCount == 240
+wmsDeliveryAttempts == 480
+wmsBusinessEffects == 240
+deadlocks == 0
+totalSafetyViolations == 0
+```
+
+此外，现有故障矩阵、60 条安全场景和全部 Maven 测试必须继续通过。
+
+## 11. 报告与证据
+
+生成新的独立证据目录，不覆盖旧运行：
+
+```text
+outputs/wcs-history-driven-center-dispatch-<runId>/
+  summary.json
+  task-results.csv
+  tick-events.csv
+  invariant-results.json
+  readable-report.xlsx
+  manifest.sha256
+```
+
+报告必须新增：
+
+- 地图快照行数、可通行节点数、地图 SHA 和规划算法版本。
+- `path_infoUsedForPlanning=false`。
+- 每条任务的业务端点、解析后物理端点、历史路径和中心新规划路径。
+- 方向预约、清障任务、HOLD、重试和重新选车明细。
+- 240/0/0 状态、每车完成数、耗时分位数和安全不变量。
+
+首页继续标明：真实历史负载驱动纯内存仿真，不是现场 SHADOW/HIL/ACTIVE 验收。
+
+## 12. 明确边界
+
+本设计证明完整静态地图上的中心调度功能、确定性、故障恢复和资源安全；它不证明实时地图与
+现场一致、真实 PLC 时序、SQL 事务、WMS 网络交付或生产吞吐能力。完整地图快照发生变化时，
+必须生成新版本和新证据，不能沿用旧结论。
diff --git a/docs/superpowers/specs/2026-07-31-wcs-real-history-driven-dispatch-simulation-design.md b/docs/superpowers/specs/2026-07-31-wcs-real-history-driven-dispatch-simulation-design.md
index d7e8222..4ce2eec 100644
--- a/docs/superpowers/specs/2026-07-31-wcs-real-history-driven-dispatch-simulation-design.md
+++ b/docs/superpowers/specs/2026-07-31-wcs-real-history-driven-dispatch-simulation-design.md
@@ -1,5 +1,9 @@
 # WCS 真实历史负载驱动全链路调度仿真设计
 
+> **已取代：** 本设计允许从历史 `path_info` 推导测试拓扑，并允许报告
+> `WAITING/FAILED`。经业务确认，这两个前提均不符合最终验收要求。后续实现以
+> `2026-07-31-wcs-complete-center-dispatch-simulation-design.md` 为唯一依据。
+
 ## 1. 目标
 
 把 `FT546-wcs.dbo.wcs_srgv_queue_finish` 固化的 240 条真实任务作为业务负载输入，验证调度中心从任务到达、重新选车、重新规划路径、交通裁决、模拟协议下发、逐段移动、资源释放到完成归档的完整功能。历史车辆号、历史路径和历史完成时间只作为对照，不控制仿真结果。