docs: design p0-b1 shadow demo expansion
This commit is contained in:
@@ -0,0 +1,216 @@
|
||||
# WCS P0-B1 离线 SHADOW Demo 增量设计
|
||||
|
||||
## 1. 背景
|
||||
|
||||
现有 `javaTest` 已实现一个 Java 8、纯内存、无外部 I/O 的 LEGACY 调度演示，覆盖任务准入、确定性选车、网格寻路、通道避让、协议失败重试和业务队列归档。
|
||||
|
||||
本增量依据仓库根目录 `docs/WCS算法优化` 的设计基线继续扩展，但不复制生产工程，也不把未签字的 PLC、提升机或 ACTIVE 能力描述为已经可用。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
在保留现有 LEGACY Demo 行为和测试的前提下，旁路增加可独立测试的 P0-B1 离线 SHADOW 领域内核：
|
||||
|
||||
1. 编译并校验版本化不可变交通地图。
|
||||
2. 使用节点、无向边和显式冲突资源表达空间硬路权。
|
||||
3. 建模交通区段与资源保护状态。
|
||||
4. 冻结带版本和序号的复合交通快照。
|
||||
5. 生成确定性的 `GRANT/HOLD/YIELD` 决策。
|
||||
6. 通过等待图拒绝会形成环的放行组合。
|
||||
7. 根据匹配反馈逐步释放资源；错配、重启或失联时 fail closed。
|
||||
8. 记录结构化决策事件，并能用相同输入离线回放出相同结果。
|
||||
9. 证明 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`，避免把交通生命周期重新塞回业务队列：
|
||||
|
||||
```text
|
||||
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 资源键
|
||||
|
||||
首个增量实现：
|
||||
|
||||
```text
|
||||
NODE:{siteId}
|
||||
EDGE:{smallerSiteId}:{largerSiteId}
|
||||
CONFLICT:{resourceCode}
|
||||
```
|
||||
|
||||
提升机和深位资源只保留扩展类型及 fail-closed 占位，不模拟真实放行。
|
||||
|
||||
### 5.3 资源保护
|
||||
|
||||
预约状态为：
|
||||
|
||||
```text
|
||||
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()` 固定执行：
|
||||
|
||||
1. 校验模式必须为 `SHADOW`，地图和快照版本必须匹配。
|
||||
2. 冻结输入并登记故障、失联、`HARD/UNKNOWN_HARD` 为不可穿越资源。
|
||||
3. 为车辆生成软路径及下一候选区段。
|
||||
4. 按业务优先级、等待老化、清区代价、任务号和车辆号稳定排序。
|
||||
5. 逐候选检查节点、无向边、显式冲突资源和容量。
|
||||
6. 构建等待图；会形成环的候选不得 GRANT。
|
||||
7. 无冲突输出 `GRANT`；可安全等待输出 `HOLD`；只有存在已发布安全让行点时输出 `YIELD`。
|
||||
8. 记录结构化原因码、冲突资源、阻挡车辆和输入哈希。
|
||||
9. 通过禁写端口记录“意图”，不得发送或改变权威状态。
|
||||
|
||||
高优先级任务不能撤销已经提交的硬区段。没有安全 YIELD 点时保持 HOLD 并记录报警原因。
|
||||
|
||||
## 8. 反馈与失效关闭
|
||||
|
||||
`FeedbackReconciler` 只有在以下字段匹配时才允许释放：
|
||||
|
||||
- `plcBootId`
|
||||
- `plannerEpoch`
|
||||
- `planVersion`
|
||||
- `segmentSeq`
|
||||
- 单调 `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 个测试通过，并新增：
|
||||
|
||||
1. 地图编译：版本、校验和、边规范键、区域非互斥、唯一出口。
|
||||
2. 资源账本：同节点、对向边、容量、非冲突并行。
|
||||
3. 状态机：非法跳转、单车单硬区段、未知提交保留。
|
||||
4. 快照：冻结、陈旧、倒退、bootId 改变。
|
||||
5. 决策：确定性排序、硬区段不可撤销、等待环、HOLD/YIELD。
|
||||
6. 反馈：逐步释放、重复快照、跳点、倒退、版本错配、ETA 到期。
|
||||
7. SHADOW：零 PLC 写、零业务状态写、零权威预约写。
|
||||
8. 回放：JSON 黄金场景稳定一致。
|
||||
9. 固定种子属性测试：资源容量不超限、等待图无环、未知资源不释放；失败信息输出 seed、地图版本和输入摘要。
|
||||
|
||||
验证命令：
|
||||
|
||||
```bash
|
||||
cd javaTest
|
||||
mvn clean test
|
||||
mvn exec:java
|
||||
```
|
||||
|
||||
验收必须读取 Surefire 汇总，确认测试数大于 0，失败和错误均为 0。控制台演示新增 SHADOW 决策与 LEGACY 对比摘要，同时保留现有事件。
|
||||
|
||||
## 12. 交付标准
|
||||
|
||||
1. 现有 LEGACY Demo 及测试无回归。
|
||||
2. SHADOW 内核拥有独立包和明确端口，不依赖生产模块。
|
||||
3. 文档测试矩阵中适用于 P0-B1 离线领域层的场景均有测试。
|
||||
4. 相同输入、地图和参数版本产生相同决定。
|
||||
5. 未知、错配、重启和失联均不会释放资源或产生新 GRANT。
|
||||
6. SHADOW 协调器无法写 PLC、业务状态或权威预约。
|
||||
7. README 明确能力边界、运行命令和非现场证据属性。
|
||||
8. 不修改 `ruoyi-*` 生产代码，不连接数据库、PLC 或 WMS。
|
||||
|
||||
Reference in New Issue
Block a user