# 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。