429 lines
18 KiB
Markdown
429 lines
18 KiB
Markdown
# WCS Dispatch and Traffic Demo Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 在工作树根目录创建独立的 Java 8 Maven Demo，用真实 JUnit 5 测试模拟 LEGACY WCS 的中心调度、确定性选车、路径交通管制、避让和队列生命周期。
|
||
|
||
**Architecture:** `LegacyDispatchCenter` 是单周期入口，只调用一次任务准入，再稳定处理车辆和活动队列。`VehicleAssignmentService`、`TrafficController`、`GridPathPlanner`、`SimulatedProtocolAdapter` 均为纯 Java 边界；`InMemoryWcsState` 保存模拟任务、队列、车辆和历史，不连接生产数据库或 PLC。
|
||
|
||
**Tech Stack:** Java 8、Maven 3.6、JUnit Jupiter 5.10.2、Maven Surefire 3.2.5、Exec Maven Plugin 3.1.0。
|
||
|
||
## Global Constraints
|
||
|
||
- 生产控制模式保持 LEGACY；Demo 不修改生产 WCS 源码。
|
||
- 不连接 SQL Server、PLC、WMS 或 Spring，不产生真实设备写入。
|
||
- 不建立生产中央路权服务，不写交通运行表，不启用 SHADOW/ACTIVE。
|
||
- 不使用 `default02` 至 `default08` 保存新增交通状态。
|
||
- 所有源码使用 Java 8 可用语法与 API。
|
||
- `mvn test` 的真实测试数必须大于 0，failures 和 errors 必须为 0。
|
||
- 车辆资格固定为 connected、`workMode=5`、`status=1`、`allowSend=true`、`battery>30`。
|
||
- 选择顺序固定为同层、绝对楼层差、Y 距离、X 距离、vehicleId。
|
||
- 队列状态保持旧语义：新建 `issued=0/executionStatus=1`，下发 `1/3`，完成 `1/4` 后归档删除。
|
||
|
||
---
|
||
|
||
## File Map
|
||
|
||
### Build and documentation
|
||
|
||
- `javaTest/pom.xml`：独立 Maven 构建、JUnit 5、Surefire、Exec 插件。
|
||
- `javaTest/README.md`：运行方式、场景、LEGACY 安全边界。
|
||
|
||
### Domain
|
||
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/model/Site.java`：站点、楼层和坐标值对象。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/model/VehicleSnapshot.java`：不可变车辆执行快照。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/model/DispatchTask.java`：业务任务及准入状态。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/model/DispatchQueueEntry.java`：活动队列及旧状态码流转。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/model/DecisionCode.java`：调度和交通决策码。
|
||
|
||
### State and scheduling
|
||
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/repository/InMemoryWcsState.java`：车辆、任务、队列、历史和每周期事件。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/center/VehicleAssignmentDecision.java`：确定性选车结果和理由。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/center/VehicleAssignmentService.java`：车辆资格过滤和稳定比较器。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/center/QueueAdmissionService.java`：每周期把一个待处理任务转为活动队列。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/center/CycleResult.java`：单周期已处理车辆和事件快照。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/center/LegacyDispatchCenter.java`：单周期中心调度入口。
|
||
|
||
### Traffic and protocol
|
||
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/traffic/GridMap.java`：站点、边和静态障碍。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/traffic/GridPathPlanner.java`：确定性广度优先最短路。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/traffic/TrafficDecision.java`：路径、HOLD 或避让结果。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/traffic/TrafficController.java`：剩余路径锁、离线点、通道冲突和避让去重。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/simulation/SimulatedProtocolAdapter.java`：可注入失败的无 I/O 下发适配器。
|
||
- `javaTest/src/main/java/com/ft546/wcs/demo/DemoApplication.java`：构造场景、推进周期和打印结果。
|
||
|
||
### Tests
|
||
|
||
- `javaTest/src/test/java/com/ft546/wcs/demo/VehicleAssignmentServiceTest.java`
|
||
- `javaTest/src/test/java/com/ft546/wcs/demo/TrafficControllerTest.java`
|
||
- `javaTest/src/test/java/com/ft546/wcs/demo/LegacyDispatchCenterTest.java`
|
||
- `javaTest/src/test/java/com/ft546/wcs/demo/QueueLifecycleTest.java`
|
||
- `javaTest/src/test/java/com/ft546/wcs/demo/DemoScenarioTest.java`
|
||
|
||
---
|
||
|
||
## Task 1: Bootstrap Real JUnit 5 and Domain Models
|
||
|
||
**Files:**
|
||
- Create: `javaTest/pom.xml`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/model/Site.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/model/VehicleSnapshot.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/model/DispatchTask.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/model/DispatchQueueEntry.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/model/DecisionCode.java`
|
||
- Test: `javaTest/src/test/java/com/ft546/wcs/demo/QueueLifecycleTest.java`
|
||
|
||
**Interfaces:**
|
||
- Produces: `Site(String id, int floor, int x, int y, String channel)`
|
||
- Produces: `VehicleSnapshot(String vehicleId, int floor, String currentSite, int workMode, int status, int battery, boolean connected, boolean allowSend, boolean cargo)`
|
||
- Produces: `DispatchTask(String taskId, TaskType type, String sourceSite, String targetSite, int floor, int priority)`
|
||
- Produces: `DispatchQueueEntry.business(DispatchTask task, String vehicleId)`
|
||
- Produces: `markIssued(List<String> path)`, `markCompleted()`, `isIssued()`, `getExecutionStatus()`
|
||
|
||
- [ ] **Step 1: Add Maven build and write the failing lifecycle test**
|
||
|
||
`pom.xml` must set `maven.compiler.source` and `target` to `1.8`, add `org.junit.jupiter:junit-jupiter:5.10.2`, configure `maven-surefire-plugin:3.2.5`, and configure `exec-maven-plugin:3.1.0` with main class `com.ft546.wcs.demo.DemoApplication`.
|
||
|
||
The first test:
|
||
|
||
```java
|
||
@Test
|
||
void queueUsesLegacyLifecycleCodes() {
|
||
DispatchTask task = new DispatchTask("T-1", TaskType.OUTBOUND, "A", "B", 1, 2);
|
||
DispatchQueueEntry queue = DispatchQueueEntry.business(task, "1");
|
||
assertEquals(0, queue.getIssued());
|
||
assertEquals(1, queue.getExecutionStatus());
|
||
queue.markIssued(Arrays.asList("A", "B"));
|
||
assertEquals(1, queue.getIssued());
|
||
assertEquals(3, queue.getExecutionStatus());
|
||
queue.markCompleted();
|
||
assertEquals(4, queue.getExecutionStatus());
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Run the focused test and verify RED**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=QueueLifecycleTest test`
|
||
|
||
Expected: FAIL during test compilation because domain classes do not exist.
|
||
|
||
- [ ] **Step 3: Implement immutable inputs and guarded queue transitions**
|
||
|
||
Implement nested enum `DispatchTask.TaskType { INBOUND, OUTBOUND, RELOCATION }`. Reject blank IDs, battery outside 0–100, non-positive floors and `markCompleted()` before issue with `IllegalStateException`. Copy path input into an unmodifiable list.
|
||
|
||
- [ ] **Step 4: Run the focused test and verify GREEN**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=QueueLifecycleTest test`
|
||
|
||
Expected: tests=1, failures=0, errors=0.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add javaTest/pom.xml javaTest/src/main/java/com/ft546/wcs/demo/model javaTest/src/test/java/com/ft546/wcs/demo/QueueLifecycleTest.java
|
||
git commit -m "test: bootstrap wcs demo domain"
|
||
```
|
||
|
||
## Task 2: Deterministic Vehicle Assignment
|
||
|
||
**Files:**
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/center/VehicleAssignmentDecision.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/center/VehicleAssignmentService.java`
|
||
- Test: `javaTest/src/test/java/com/ft546/wcs/demo/VehicleAssignmentServiceTest.java`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `DispatchTask`, `VehicleSnapshot`, `Map<String, Site>`
|
||
- Produces: `VehicleAssignmentDecision select(DispatchTask task, List<VehicleSnapshot> vehicles, Map<String, Site> sites)`
|
||
- Produces: `DecisionCode.ASSIGNED`, `HOLD_NO_ELIGIBLE_VEHICLE`, `REJECT_INVALID_SITE`
|
||
- Produces: `Optional<VehicleSnapshot> getVehicle()`, `DecisionCode getCode()`, `String getReason()`
|
||
|
||
- [ ] **Step 1: Write failing assignment tests**
|
||
|
||
Tests must assert:
|
||
|
||
```java
|
||
assertEquals("2", service.select(task, Arrays.asList(crossFloor, sameFloor), sites)
|
||
.getVehicle().get().getVehicleId());
|
||
```
|
||
|
||
```java
|
||
assertEquals("1", service.select(task, Arrays.asList(vehicle2, vehicle1), sites)
|
||
.getVehicle().get().getVehicleId());
|
||
```
|
||
|
||
Also assert ineligible vehicles are excluded and a missing source site returns `REJECT_INVALID_SITE`.
|
||
|
||
- [ ] **Step 2: Run and verify RED**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=VehicleAssignmentServiceTest test`
|
||
|
||
Expected: FAIL because assignment types do not exist.
|
||
|
||
- [ ] **Step 3: Implement stable assignment**
|
||
|
||
Eligibility is exactly `connected && workMode == 5 && status == 1 && allowSend && battery > 30`. Sort by:
|
||
|
||
```java
|
||
Comparator.comparingInt(candidate -> candidate.sameFloorPenalty)
|
||
.thenComparingInt(candidate -> candidate.floorDistance)
|
||
.thenComparingInt(candidate -> candidate.yDistance)
|
||
.thenComparingInt(candidate -> candidate.xDistance)
|
||
.thenComparing(candidate -> candidate.vehicle.getVehicleId());
|
||
```
|
||
|
||
Distances use `Site` coordinates; never parse malformed numeric substrings from site IDs. Return a reason string containing the chosen comparison values.
|
||
|
||
- [ ] **Step 4: Run and verify GREEN**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=VehicleAssignmentServiceTest test`
|
||
|
||
Expected: all assignment tests pass.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add javaTest/src/main/java/com/ft546/wcs/demo/center javaTest/src/test/java/com/ft546/wcs/demo/VehicleAssignmentServiceTest.java
|
||
git commit -m "feat: add deterministic vehicle assignment demo"
|
||
```
|
||
|
||
## Task 3: Grid Path Planning and Traffic Control
|
||
|
||
**Files:**
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/traffic/GridMap.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/traffic/GridPathPlanner.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/traffic/TrafficDecision.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/traffic/TrafficController.java`
|
||
- Test: `javaTest/src/test/java/com/ft546/wcs/demo/TrafficControllerTest.java`
|
||
|
||
**Interfaces:**
|
||
- Consumes: sites, adjacency, static blocks, vehicles and active queues
|
||
- Produces: `List<String> shortestPath(GridMap map, String start, String end, Set<String> blocked)`
|
||
- Produces: `TrafficDecision plan(VehicleSnapshot vehicle, DispatchQueueEntry queue, Collection<VehicleSnapshot> vehicles, Collection<DispatchQueueEntry> queues)`
|
||
- Produces: `PATH_READY`, `HOLD_NO_PATH`, `HOLD_CHANNEL_BLOCKED`, `AVOIDANCE_CREATED`
|
||
|
||
- [ ] **Step 1: Write failing path and traffic tests**
|
||
|
||
Cover:
|
||
|
||
```java
|
||
assertEquals(Arrays.asList("A", "D", "C"), planner.shortestPath(map, "A", "C",
|
||
Collections.singleton("B")));
|
||
```
|
||
|
||
```java
|
||
TrafficDecision decision = controller.plan(car1, car1Queue, vehicles, queues);
|
||
assertEquals(DecisionCode.AVOIDANCE_CREATED, decision.getCode());
|
||
assertEquals(9, decision.getAvoidanceQueue().get().getPriority());
|
||
```
|
||
|
||
Also test offline current-site locking, no route, avoidance de-duplication, and successful re-plan after avoidance queue deletion.
|
||
|
||
- [ ] **Step 2: Run and verify RED**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=TrafficControllerTest test`
|
||
|
||
Expected: FAIL because traffic types do not exist.
|
||
|
||
- [ ] **Step 3: Implement deterministic BFS and occupancy view**
|
||
|
||
`GridPathPlanner` visits neighbors sorted by site ID. `TrafficController` blocks:
|
||
|
||
1. static map obstacles,
|
||
2. disconnected vehicle current sites,
|
||
3. every other active queue path from that vehicle's current-site index onward.
|
||
|
||
Before planning a business queue, detect a same-floor vehicle at a different site with the same target channel. If it has no active queue, create `DispatchQueueEntry.avoidance(...)` to a configured cache site, priority 9. If it already has an avoidance queue, return `HOLD_CHANNEL_BLOCKED` without creating another.
|
||
|
||
- [ ] **Step 4: Run and verify GREEN**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=TrafficControllerTest test`
|
||
|
||
Expected: all traffic tests pass.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add javaTest/src/main/java/com/ft546/wcs/demo/traffic javaTest/src/test/java/com/ft546/wcs/demo/TrafficControllerTest.java
|
||
git commit -m "feat: simulate wcs traffic control"
|
||
```
|
||
|
||
## Task 4: In-Memory State, Admission, and Cycle Coordinator
|
||
|
||
**Files:**
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/repository/InMemoryWcsState.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/center/QueueAdmissionService.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/center/CycleResult.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/center/LegacyDispatchCenter.java`
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/simulation/SimulatedProtocolAdapter.java`
|
||
- Test: `javaTest/src/test/java/com/ft546/wcs/demo/LegacyDispatchCenterTest.java`
|
||
|
||
**Interfaces:**
|
||
- Produces: `CycleResult runCycle()`
|
||
- Produces: `int getAdmissionInvocationCount()`
|
||
- Produces: `Optional<DispatchQueueEntry> createPendingQueue(InMemoryWcsState state)`
|
||
- Produces: state methods to add/update vehicles and tasks, query active queues/history/events
|
||
- Produces: `SimulatedProtocolAdapter.ProtocolResult send(DispatchQueueEntry queue, List<String> path)`
|
||
|
||
- [ ] **Step 1: Write failing coordinator tests**
|
||
|
||
The first test:
|
||
|
||
```java
|
||
CycleResult result = center.runCycle();
|
||
assertEquals(1, admission.getInvocationCount());
|
||
assertEquals(Arrays.asList("1", "2", "3"), result.getProcessedVehicleIds());
|
||
assertEquals(1, state.getActiveQueues().size());
|
||
```
|
||
|
||
Also test protocol failure leaves `issued=0/executionStatus=1`, the next cycle retries successfully, and reaching the destination archives and deletes the queue exactly once.
|
||
|
||
- [ ] **Step 2: Run and verify RED**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=LegacyDispatchCenterTest test`
|
||
|
||
Expected: FAIL because coordinator types do not exist.
|
||
|
||
- [ ] **Step 3: Implement one-admission-per-cycle coordinator**
|
||
|
||
`runCycle()` must:
|
||
|
||
1. call admission exactly once,
|
||
2. freeze and sort vehicle IDs,
|
||
3. add any avoidance queue returned by traffic control,
|
||
4. only send a queue when `PATH_READY`,
|
||
5. leave HOLD queues unchanged,
|
||
6. call protocol once per unissued ready queue,
|
||
7. complete and archive an issued queue only when vehicle current site equals queue end site.
|
||
|
||
`SimulatedProtocolAdapter.failNextSend()` injects one failure and records every attempted queue ID without I/O.
|
||
|
||
- [ ] **Step 4: Run and verify GREEN**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=LegacyDispatchCenterTest,QueueLifecycleTest test`
|
||
|
||
Expected: coordinator and lifecycle tests pass.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add javaTest/src/main/java/com/ft546/wcs/demo/repository javaTest/src/main/java/com/ft546/wcs/demo/center javaTest/src/main/java/com/ft546/wcs/demo/simulation javaTest/src/test/java/com/ft546/wcs/demo/LegacyDispatchCenterTest.java
|
||
git commit -m "feat: add legacy dispatch cycle demo"
|
||
```
|
||
|
||
## Task 5: Executable Scenarios and End-to-End Test
|
||
|
||
**Files:**
|
||
- Create: `javaTest/src/main/java/com/ft546/wcs/demo/DemoApplication.java`
|
||
- Create: `javaTest/src/test/java/com/ft546/wcs/demo/DemoScenarioTest.java`
|
||
- Create: `javaTest/README.md`
|
||
|
||
**Interfaces:**
|
||
- Produces: `DemoApplication.runScenario(PrintStream out)`
|
||
- Produces: console lines beginning `CYCLE`, `ASSIGN`, `PATH`, `HOLD`, `AVOID`, `SEND`, `COMPLETE`, `SUMMARY`
|
||
|
||
- [ ] **Step 1: Write failing end-to-end test**
|
||
|
||
```java
|
||
ByteArrayOutputStream output = new ByteArrayOutputStream();
|
||
DemoApplication.runScenario(new PrintStream(output));
|
||
String text = new String(output.toByteArray(), StandardCharsets.UTF_8);
|
||
assertTrue(text.contains("ASSIGN"));
|
||
assertTrue(text.contains("AVOID"));
|
||
assertTrue(text.contains("HOLD"));
|
||
assertTrue(text.contains("SEND"));
|
||
assertTrue(text.contains("COMPLETE"));
|
||
assertTrue(text.contains("SUMMARY"));
|
||
```
|
||
|
||
- [ ] **Step 2: Run and verify RED**
|
||
|
||
Run: `cd javaTest && mvn -Dtest=DemoScenarioTest test`
|
||
|
||
Expected: FAIL because `DemoApplication` does not exist.
|
||
|
||
- [ ] **Step 3: Implement the complete console scenario**
|
||
|
||
Create a two-lane map with a cache point and three vehicles. Run sequential phases for deterministic assignment, same-channel avoidance, avoidance completion, protocol failure/retry, business completion and no-path HOLD. Print every event and a final summary containing cycle count, active queue count and history count.
|
||
|
||
`README.md` must document:
|
||
|
||
```bash
|
||
mvn test
|
||
mvn exec:java
|
||
```
|
||
|
||
and explicitly state the Demo never connects to production systems.
|
||
|
||
- [ ] **Step 4: Run focused and full verification**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd javaTest
|
||
mvn -Dtest=DemoScenarioTest test
|
||
mvn test
|
||
mvn exec:java
|
||
```
|
||
|
||
Expected: focused test passes; full Surefire summary has tests > 0, failures=0, errors=0; console output contains all required event types and exits 0.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add javaTest/src/main/java/com/ft546/wcs/demo/DemoApplication.java javaTest/src/test/java/com/ft546/wcs/demo/DemoScenarioTest.java javaTest/README.md
|
||
git commit -m "feat: add executable wcs dispatch simulation"
|
||
```
|
||
|
||
## Task 6: Completion Audit
|
||
|
||
**Files:**
|
||
- Verify: `javaTest/**`
|
||
- Verify: `docs/superpowers/specs/2026-07-30-wcs-dispatch-traffic-demo-design.md`
|
||
|
||
**Interfaces:**
|
||
- Consumes: all earlier tasks
|
||
- Produces: objective-by-objective evidence
|
||
|
||
- [ ] **Step 1: Verify repository and Java compatibility**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git rev-parse --is-inside-work-tree
|
||
mvn -f javaTest/pom.xml clean test
|
||
```
|
||
|
||
Expected: Git prints `true`; Maven exits 0 and compiles with source/target 1.8.
|
||
|
||
- [ ] **Step 2: Verify real test counts**
|
||
|
||
Inspect `javaTest/target/surefire-reports/TEST-*.xml`; sum `tests`, `failures`, `errors`, and `skipped`.
|
||
|
||
Expected: tests > 0, failures=0, errors=0.
|
||
|
||
- [ ] **Step 3: Verify executable behavior**
|
||
|
||
Run: `mvn -f javaTest/pom.xml exec:java`
|
||
|
||
Expected: output includes `CYCLE`, `ASSIGN`, `PATH`, `HOLD`, `AVOID`, `SEND`, `COMPLETE`, and `SUMMARY`, with process exit 0.
|
||
|
||
- [ ] **Step 4: Verify production isolation**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git diff 7b36dfa --name-only
|
||
```
|
||
|
||
Expected: only `javaTest/**` and the implementation plan are added or modified; no production `ruoyi-*` code changes.
|
||
|
||
- [ ] **Step 5: Final commit if verification updates documentation**
|
||
|
||
```bash
|
||
git add javaTest docs/superpowers/plans/2026-07-30-wcs-dispatch-traffic-demo.md
|
||
git commit -m "docs: finalize wcs demo verification"
|
||
```
|