183 lines
11 KiB
Markdown
183 lines
11 KiB
Markdown
# FT546 WCS 中心调度与交通管制 Demo
|
||
|
||
这是一个独立的 Java 8 Maven Demo。它保留 FT546 WCS 的 LEGACY 调度模拟，并旁路提供 P0-B1 离线 SHADOW 交通决策内核。
|
||
|
||
## 安全边界
|
||
|
||
- 仅使用内存车辆、任务、队列和地图。
|
||
- 不启动 Spring，不连接 SQL Server、PLC 或 WMS。
|
||
- 不发送真实设备命令。
|
||
- 不修改生产 `ruoyi-*` 模块。
|
||
- SHADOW 仅在离线内存中计算、记录和回放，写端口会直接拒绝调用。
|
||
- 不启用现场 SHADOW、HIL、LIMITED_ACTIVE、ACTIVE 或 PRODUCTION。
|
||
- 不把离线模拟结果作为现场证据。
|
||
|
||
## 已覆盖行为
|
||
|
||
- 每个调度周期只执行一次业务任务准入。
|
||
- 在线、自动、空闲、允许下发且电量大于 30 的车辆才可参与分配。
|
||
- 同层、楼层差、Y 距离、X 距离、车辆编号的稳定选车规则。
|
||
- 其他车辆剩余路径和离线车辆当前位置锁定。
|
||
- 同通道阻挡、高优先级避让任务和避让去重。
|
||
- 模拟协议失败、下一周期重试。
|
||
- 队列 `0/1 → 1/3 → 1/4` 状态流转、完成归档和占用释放。
|
||
- 无路可达时返回 HOLD，而不是抛出空指针。
|
||
|
||
## P0-B1 离线 SHADOW 覆盖
|
||
|
||
- 带版本、区域确认和基础地图校验和的不可变交通地图。
|
||
- `NODE`、规范化无向 `EDGE` 和显式 `CONFLICT` 资源及容量。
|
||
- `SOFT/COMMIT_GUARD/HARD/UNKNOWN_HARD/RELEASED` 资源保护契约。
|
||
- 区段 Prepare/Commit 状态机及非法跳转拒绝。
|
||
- 带 `plcBootId/heartbeatSeq/snapshotSeq` 的不可变复合快照。
|
||
- 陈旧、序号倒退、PLC 重启、失联和人工模式的 fail-closed 检查。
|
||
- 确定性 `GRANT/HOLD/YIELD`、等待图环拒绝及安全让行点门禁。
|
||
- 匹配反馈逐步释放；重复、跳点、版本错配和 ACK 未知不释放。
|
||
- SHADOW PLC、业务状态和权威预约三类禁写端口。
|
||
- JSON 黄金决策事件、SHA-256 输入哈希和离线回放。
|
||
- 固定种子 `546001` 至 `546010` 的容量、无环和确定性不变量回归。
|
||
- `shadow-simulation-60.json` 提供 60 条独立模拟数据，覆盖 12 类资源、决策、快照和反馈场景；每条数据由参数化测试独立计数。
|
||
- `shadow/history` 保存从 `FT546-wcs.dbo.wcs_srgv_queue_finish` 只读抽取的 240 条真实队列历史样本，并独立保存 `dbo.wcs_srgv_map` 的 2,552 行完整网格快照；任务历史路径不用于构建地图。
|
||
- 真实历史数据覆盖车辆 `1/2/3` 和任务类型 `1/2/3`；数据库全量扫描口径为 17,136 条，其中 11,943 条带有非空路径。
|
||
- 历史回放使用 `[create_date, finish_date)` 推导潜在并发窗口；数据库“已完成”事实与当前 SHADOW 的 `GRANT/HOLD/INSUFFICIENT_DATA` 推演结果分栏记录。
|
||
|
||
`com.ft546.wcs.demo` 是 LEGACY 演示；新增能力位于 `com.ft546.wcs.shadow`，交通区段状态不会写入 LEGACY 业务队列。
|
||
|
||
## 有界冲突感知路径规划
|
||
|
||
- `GridPathPlanner` 保留原 BFS 行为作为兼容基线；历史调度仿真使用独立的有界候选规划器。
|
||
- 候选规划先按地图坐标欧氏距离求确定性最短路，再用 Yen 算法枚举无环候选；只保留最短距离
|
||
`110%` 以内的路线，最多输出 32 条。
|
||
- 候选不使用加权总分，而是依次比较对向冲突、占用节点、不兼容边预约、活动路线重叠、
|
||
转弯、坐标距离和规范站点序列；前一项优先于全部后一项。
|
||
- 自动选车规则保持不变。选车完成后，车辆到任务源点的接近段和源点到目标的服务段分别生成、
|
||
评价候选，再拼成实际执行路线。
|
||
- 临时交通冲突不会被误判为永久无路。只有地图端点未知或静态候选集合为空才以 `NO_ROUTE`
|
||
失效关闭；可达但暂时冲突的任务继续走预约和 HOLD 流程。
|
||
- 同一车辆、任务、阻塞资源和交通原因连续 HOLD 三次时触发重规划。新剩余路线必须严格更优，
|
||
且走廊预约原子替换成功后才生效；换路后至少 MOVE 一个节点才允许再次普通重规划。
|
||
- PLC 发送失败、断线、重启、低电量和车辆故障不计入交通 HOLD 连续次数，各自按协议重试、
|
||
恢复或重新调度流程处理。
|
||
- 历史 `path_info` 从不作为规划输入。只有路径全部位于权威地图且首尾等于本次解析的物理业务
|
||
端点时，才进入 `EXACT_MATCH/SHORTER_PHYSICAL_DISTANCE/SAME_DISTANCE_BETTER_QUALITY/
|
||
BOUNDED_DETOUR_FEWER_CONFLICTS/WORSE_QUALITY` 公平比较；其他记录标记为端点不一致或历史路径无效。
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
mvn clean test
|
||
```
|
||
|
||
测试必须由 Maven Surefire 实际发现并执行；验收标准为测试数大于 0、Failures 为 0、Errors 为 0。
|
||
|
||
真实历史专项测试：
|
||
|
||
```bash
|
||
mvn -Dtest=HistoricalQueueDatabaseReplayTest test
|
||
```
|
||
|
||
生成真实历史离线回放证据：
|
||
|
||
```bash
|
||
mvn compile exec:java \
|
||
-Dexec.mainClass=com.ft546.wcs.shadow.history.HistoricalReplayApplication \
|
||
-Dexec.args="outputs/wcs-shadow-history-replay-local"
|
||
```
|
||
|
||
输出包括 `summary.json`、`replay-results.csv`、`data-quality-issues.csv` 和
|
||
`manifest.sha256`。报告保留数据库原始业务编号，方便回查。
|
||
|
||
> 这些结果是“真实历史队列离线回放”，不是现场 SHADOW 验收。历史队列表没有保存
|
||
> 当时每一轮 PLC 快照、资源账本或 LEGACY 决策，因此不能把最终完成状态当作算法正确率。
|
||
|
||
## 运行真实历史负载全链路调度仿真
|
||
|
||
240 条历史记录按 `create_date` 生成到达事件，默认按 `100x` 加速。调度中心重新选车和
|
||
规划路径，经过 SHADOW 交通裁决、模拟 PLC/ACK、逐节点移动、资源释放、完成归档和
|
||
幂等 WMS 回调。历史 `agv_id/path_info/finish_date/完成状态` 仅用于对照。
|
||
|
||
```bash
|
||
mvn compile exec:java \
|
||
-Dexec.mainClass=com.ft546.wcs.shadow.history.simulation.HistoricalDispatchSimulationApplication \
|
||
-Dexec.args="outputs/wcs-history-driven-center-dispatch-local 100"
|
||
```
|
||
|
||
第二个参数只允许 `10` 或 `100`。Java 原始证据包括 `summary.json`、`route-decisions.json`、
|
||
`task-results.csv`、`tick-events.csv`、`invariant-results.json` 和 `manifest.sha256`，回答完成/等待/失败、
|
||
每车完成数、车辆和路径差异、资源安全、平均/P95/P99、HOLD/重试原因、历史耗时差异、
|
||
归档和 WMS 幂等情况。正式验收证据目录另包含由这些原始证据生成的
|
||
`readable-report.xlsx`，并纳入 `manifest.sha256`。
|
||
每个已完成任务会注入一次重复 WMS 投递，用于验证接收端幂等；报告分别记录
|
||
`wmsDuplicateDeliveryAttempts` 和 `wmsDuplicateBusinessEffects`，验收要求后者为 `0`。
|
||
任务到达时间按相邻 `create_date` 的真实间隔除以加速倍率计算，长空闲间隔不截断。
|
||
等待和完成时间用于观察本次确定性仿真流程，不进入车辆选择或路径质量元组。历史环境中的故障、
|
||
拥堵和 PLC 时序没有完整快照，因此仿真耗时与历史耗时的差值不能单独证明路线优劣或现场产能。
|
||
|
||
> 这是“真实历史负载驱动纯内存仿真”，不是现场 SHADOW、HIL 或 ACTIVE 验收。
|
||
> 历史表不含独立的仿真起始时刻车辆位置/状态快照，因此车辆 `1/2/3` 分别从完整地图中的
|
||
> 固定站点 `010701/010702/010703` 初始化；历史 `agv_id` 仅用于对照，不参与初始位置或选车约束。
|
||
|
||
## 打开调度路径审计页面
|
||
|
||
审计页面调用上述同一套 Java 调度、规划、交通裁决和仿真代码，浏览器只负责显示服务端
|
||
返回的选车、`plannedPath` 和逐 tick 事件，不在 JavaScript 中复制算法。启动命令：
|
||
|
||
```powershell
|
||
mvn compile exec:java "-Dexec.mainClass=com.ft546.wcs.shadow.history.visualizer.HistoricalDispatchVisualizerApplication" "-Dexec.args=18084"
|
||
```
|
||
|
||
浏览器访问 `http://127.0.0.1:18084`。在“A → B 单任务”中填写完整地图内的起点和终点，
|
||
选择任务类型、优先级、加速倍率及可选故障预设，然后运行调度。页面会显示中心选车、车辆到
|
||
起点的接近路径、调度中心重新规划的 A → B 路径、逐节点移动、HOLD 和 PLC 重试事件。
|
||
地图默认显示当前楼层完整拓扑。“全图”用于确认规划路径位于真实地图的哪些通道，“路径”
|
||
用于放大查看新旧路线的分叉和汇合；也可以用工具栏或鼠标滚轮缩放，按住地图拖动平移，
|
||
复位按钮恢复完整地图。楼层下拉始终包含 1-8 楼，并标出任务路径和当前车辆所在楼层。
|
||
|
||
时间线可逐事件前进、后退或自动播放。浅灰色为完整地图，灰色虚线为车辆到起点的接近路径，
|
||
绿色为调度中心当前 `plannedPath`，橙色点线为历史 `path_info` 参考，蓝色为已经通过的边；
|
||
共同路段同时保留绿色底线和橙色点线。右侧检查器分别统计共同边、仅新规划边、仅历史边，并
|
||
报告无法映射到权威地图的历史无效段；无效段只列为证据，不会被画成真实道路。关闭“历史参考”
|
||
只隐藏橙色证据，不影响绿色的新规划结果。
|
||
|
||
地图图层可分别开关历史、初始规划、当前规划、MOVE 轨迹和 HOLD 点。右侧“候选与质量”按接近段/
|
||
服务段和路径版本展示最短距离、选中距离、绕行比例、候选数量、选择原因以及完整质量元组；候选表
|
||
直接显示 Java 返回的候选和最终选中项。成功 REROUTE 事件保存换路前后剩余路径及同一交通快照的
|
||
质量，选择重规划记录后会在完整地图上同时叠加两条路线。页面不重新规划，也不自行推断地图邻接。
|
||
|
||
“240 条历史任务”会重新执行全部历史负载并列出完成、等待、失败、重新选车和路径变化；
|
||
“安全审计”集中显示节点双占、资源超容量、对向换边、死锁、归档完整性和 WMS 回调幂等。
|
||
导出的 JSON 是本次内存仿真的页面证据。
|
||
|
||
服务严格绑定 `127.0.0.1`，只读取打包的历史与地图资源，不接收任意文件路径，不连接数据库、
|
||
真实 PLC 或 WMS。按 `Ctrl+C` 停止服务。该页面用于离线上线前检查，不能替代现场 HIL/ACTIVE 验收。
|
||
|
||
服务运行时可在另一个终端执行真实 Chromium 验收；脚本会运行 A→B 和 240 条接口，并检查完整地图、
|
||
图层开关、视口、候选证据、桌面/移动布局、横向溢出及控制台错误：
|
||
|
||
```bash
|
||
python scripts/visualizer_browser_qa.py http://127.0.0.1:18084 outputs/browser-qa
|
||
```
|
||
|
||
## 运行控制台模拟
|
||
|
||
```bash
|
||
mvn exec:java
|
||
```
|
||
|
||
输出事件包括：
|
||
|
||
- `CYCLE`：调度周期开始
|
||
- `ASSIGN`：任务选车和裁决理由
|
||
- `PATH`：规划成功的路径
|
||
- `AVOID`：创建避让队列
|
||
- `HOLD`：交通或协议原因导致等待
|
||
- `SEND`：模拟协议下发成功
|
||
- `MOVE`：模拟车辆推进
|
||
- `COMPLETE`：队列完成并归档
|
||
- `SUMMARY`：最终周期、活动队列、历史和协议尝试次数
|
||
- `SHADOW-SUMMARY`：离线 SHADOW 的 GRANT/HOLD 数量和零写入声明
|
||
|
||
## 未覆盖的生产门槛
|
||
|
||
本项目不包含 SQL Server 事务与 Outbox、真实 PLC Prepare/Commit、CRC 与寄存器布局、提升机物理信号、深位真实执行、硬件在环、现场 SHADOW 样本或区域 ACTIVE 回退。相关能力仍以 `docs/WCS算法优化` 的外部签字和验收门禁为准。
|