9.0 KiB
WCS P0-B1 离线 SHADOW Demo 增量设计
1. 背景
现有 javaTest 已实现一个 Java 8、纯内存、无外部 I/O 的 LEGACY 调度演示，覆盖任务准入、确定性选车、网格寻路、通道避让、协议失败重试和业务队列归档。
本增量依据仓库根目录 docs/WCS算法优化 的设计基线继续扩展，但不复制生产工程，也不把未签字的 PLC、提升机或 ACTIVE 能力描述为已经可用。
2. 目标
在保留现有 LEGACY Demo 行为和测试的前提下，旁路增加可独立测试的 P0-B1 离线 SHADOW 领域内核：
- 编译并校验版本化不可变交通地图。
- 使用节点、无向边和显式冲突资源表达空间硬路权。
- 建模交通区段与资源保护状态。
- 冻结带版本和序号的复合交通快照。
- 生成确定性的
GRANT/HOLD/YIELD决策。 - 通过等待图拒绝会形成环的放行组合。
- 根据匹配反馈逐步释放资源；错配、重启或失联时 fail closed。
- 记录结构化决策事件，并能用相同输入离线回放出相同结果。
- 证明 SHADOW 协调器不会写 PLC、LEGACY 业务状态或权威运行时预约。
3. 明确边界
3.1 范围内
- Java 8 纯领域对象和内存测试替身。
- P0-B1 的 L1 领域测试、L4 JSON 黄金场景和小规模固定种子属性测试。
- 模拟节点、无向边、显式冲突资源及容量。
- 区段状态和资源保护状态的契约测试。
- 快照陈旧、序号倒退、
plcBootId改变和路径错配测试。 - SHADOW 决策、差异记录、禁写保护和确定性回放。
- 仅用于证明 fail-closed 行为的 PLC/提升机契约桩。
3.2 范围外
- SQL Server Schema、MyBatis Mapper、真实事务和 Outbox。
- 真实 PLC 寄存器、CRC、网络通信或硬件在环。
- 真实 WMS 回调或业务表更新。
- 深位和提升机的真实执行控制。
ACTIVE/LIMITED_ACTIVE/PRODUCTION控制模式。- 现场 SHADOW 样本、现场性能基线或任何生产验收声明。
成果状态只能描述为“离线 SHADOW 模拟验证”。所有未签字外部门禁继续保持 BLOCKED 或 IN_VERIFICATION。
4. 架构
现有 com.ft546.wcs.demo LEGACY 包保持兼容。新增 com.ft546.wcs.shadow，避免把交通生命周期重新塞回业务队列：
com.ft546.wcs.shadow/
├── map/ 版本化地图、资源键和编译校验
├── snapshot/ 不可变复合快照与新鲜度检查
├── segment/ 候选区段、区段状态机
├── resource/ 资源定义、保护状态和内存账本
├── decision/ 候选排序、等待图、GRANT/HOLD/YIELD
├── feedback/ 匹配校验、逐步释放与隔离
├── replay/ 决策事件、JSON 夹具和离线回放
└── application/SHADOW 协调器及禁写端口
LEGACY 继续拥有现有模拟发送和业务队列状态。SHADOW 只读取冻结输入，使用本轮临时计算视图，输出决策事件和差异，不改变 InMemoryWcsState 中的任务、队列或历史。
5. 地图与资源模型
5.1 版本化交通地图
TrafficMapCompiler 从内存地图定义生成 EffectiveTrafficMap。编译时验证：
mapCode、versionId和基础地图校验和匹配。- 交通区域边界已确认。
- 节点与边引用有效。
- 容量为正数。
- 无向边使用规范资源键。
- 安全等待点不是唯一出口。
交通区域只表示统一协调和版本边界，不自动成为容量 1 的资源。
5.2 资源键
首个增量实现：
NODE:{siteId}
EDGE:{smallerSiteId}:{largerSiteId}
CONFLICT:{resourceCode}
提升机和深位资源只保留扩展类型及 fail-closed 占位，不模拟真实放行。
5.3 资源保护
预约状态为：
SOFT → COMMIT_GUARD → HARD → RELEASED
↘ UNKNOWN_HARD
SOFT只参与本轮候选计算。COMMIT_GUARD排他保护提交窗口。HARD表示匹配提交事实。UNKNOWN_HARD表示 ACK 丢失、失联、重启或反馈错配，按硬资源保留。- 时间或 ETA 到期不能释放
HARD/UNKNOWN_HARD。
SHADOW 协调器不得把这些状态写入权威运行时账本；状态机通过独立领域测试和模拟执行夹具验证。
6. 快照和区段
TrafficSnapshot 在每轮开始时冻结：
tickSeq、决策时间、地图版本和参数版本。- 每车
plcBootId/heartbeatSeq/snapshotSeq。 - 当前位置、下一点、剩余路径、通信和故障状态。
- 已有硬资源、未知硬资源和资源容量。
- 待比较的 LEGACY 实际决定。
快照对象及其集合不可变。以下情况将车辆隔离并阻止新 GRANT：
- 超过新鲜度上限。
- 心跳或快照序号倒退。
plcBootId改变。- 区段版本或剩余路径不匹配。
- 通信状态未知、失联或故障。
候选区段不得跨过地图决断点、安全等待点或冲突资源边界。固定最大点数只作为技术上限。
7. 决策流程
ShadowTrafficCoordinator.decide() 固定执行：
- 校验模式必须为
SHADOW，地图和快照版本必须匹配。 - 冻结输入并登记故障、失联、
HARD/UNKNOWN_HARD为不可穿越资源。 - 为车辆生成软路径及下一候选区段。
- 按业务优先级、等待老化、清区代价、任务号和车辆号稳定排序。
- 逐候选检查节点、无向边、显式冲突资源和容量。
- 构建等待图；会形成环的候选不得 GRANT。
- 无冲突输出
GRANT；可安全等待输出HOLD；只有存在已发布安全让行点时输出YIELD。 - 记录结构化原因码、冲突资源、阻挡车辆和输入哈希。
- 通过禁写端口记录“意图”，不得发送或改变权威状态。
高优先级任务不能撤销已经提交的硬区段。没有安全 YIELD 点时保持 HOLD 并记录报警原因。
8. 反馈与失效关闭
FeedbackReconciler 只有在以下字段匹配时才允许释放：
plcBootIdplannerEpochplanVersionsegmentSeq- 单调
snapshotSeq - 当前点及剩余路径是已提交路径的合法单调后缀
匹配 A→B 后释放节点 A 和无向边 A—B，节点 B 继续保留。重复快照幂等返回。
跳点、倒退、版本错配、PLC 重启、ACK 丢失和通信中断均不得释放；相关保护转为或保持 UNKNOWN_HARD，车辆进入隔离。模拟器不能借助任务、楼层或其他字段推断未知载货状态。
9. 决策事件与回放
每轮 DecisionEvent 至少包含：
- 决策 ID、tick、地图/参数版本。
- 输入快照哈希和车辆快照序号。
- 稳定排序后的候选。
- 每车
GRANT/HOLD/YIELD、原因码、冲突资源和阻挡车辆。 - 资源变化模拟摘要。
- LEGACY 实际决定及结构化差异分类。
回放服务从 JSON 黄金夹具重建相同输入，并断言决定、原因码和资源结果完全一致。事件记录允许作为 SHADOW 的唯一旁路输出，但不得被称为现场 SHADOW 证据。
10. 错误处理
- 地图校验失败：拒绝加载，不使用旧校验和继续规划。
- 模式不是 SHADOW：协调器拒绝运行。
- 任一外部写端口调用：抛出
ShadowWriteForbiddenException。 - 资源不足或等待环：返回结构化 HOLD，不抛系统异常。
- 无安全 YIELD 点：HOLD 并记录
NO_SAFE_YIELD_SITE。 - 未知载货、提升机信号或 PLC 契约：fail closed。
- 不可恢复的模型定义错误：构造或编译阶段抛
IllegalArgumentException。
11. 测试策略
保持现有 20 个测试通过，并新增：
- 地图编译：版本、校验和、边规范键、区域非互斥、唯一出口。
- 资源账本：同节点、对向边、容量、非冲突并行。
- 状态机：非法跳转、单车单硬区段、未知提交保留。
- 快照：冻结、陈旧、倒退、bootId 改变。
- 决策：确定性排序、硬区段不可撤销、等待环、HOLD/YIELD。
- 反馈：逐步释放、重复快照、跳点、倒退、版本错配、ETA 到期。
- SHADOW：零 PLC 写、零业务状态写、零权威预约写。
- 回放：JSON 黄金场景稳定一致。
- 固定种子属性测试：资源容量不超限、等待图无环、未知资源不释放；失败信息输出 seed、地图版本和输入摘要。
验证命令：
cd javaTest
mvn clean test
mvn exec:java
验收必须读取 Surefire 汇总，确认测试数大于 0，失败和错误均为 0。控制台演示新增 SHADOW 决策与 LEGACY 对比摘要，同时保留现有事件。
12. 交付标准
- 现有 LEGACY Demo 及测试无回归。
- SHADOW 内核拥有独立包和明确端口，不依赖生产模块。
- 文档测试矩阵中适用于 P0-B1 离线领域层的场景均有测试。
- 相同输入、地图和参数版本产生相同决定。
- 未知、错配、重启和失联均不会释放资源或产生新 GRANT。
- SHADOW 协调器无法写 PLC、业务状态或权威预约。
- README 明确能力边界、运行命令和非现场证据属性。
- 不修改
ruoyi-*生产代码，不连接数据库、PLC 或 WMS。