FT546-WCS/docs/superpowers/plans/2026-08-05-javaTest-dispatch-visualizer.md

# javaTest Dispatch Visualizer 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:** Build a localhost-only HTML audit console that runs the existing Java scheduler for arbitrary A-to-B tasks and the complete 240-task historical workload, then renders selected vehicles, planned paths, tick movement, failures, and safety evidence.

**Architecture:** Add a focused point-to-point input factory beside the simulation domain, a visualizer service that invokes the existing simulator, a deterministic map-to-JSON mapper, and a Java 8 `HttpServer` that serves same-origin static assets and APIs. The browser never replans routes; it draws `plannedPath`, map coordinates, and `MOVE` events returned by Java.

**Tech Stack:** Java 8, Maven, Jackson 2.17.2, JUnit 5.10.2, JDK `HttpServer`, HTML5, CSS, vanilla JavaScript, SVG, Playwright for browser QA.

## Global Constraints

- Work only under `javaTest` plus the approved design/plan documents.
- Reuse `HistoricalDispatchSimulator`, `GridPathPlanner`, `VehicleAssignmentService`, traffic arbitration, PLC simulation, archive, and WMS idempotency logic.
- Do not add Spring, Node build dependencies, database connections, PLC connections, or WMS connections.
- Bind the visualizer to `127.0.0.1`; default port is `18084`.
- Do not accept arbitrary filesystem paths or execute user-supplied commands.
- Historical `agv_id` and `path_info` are comparison inputs only.
- The UI must distinguish approach path, service path, and traversed path.
- The UI must remain an offline audit tool and must not claim to guarantee production safety.
- Preserve unrelated worktree changes.

---

### Task 1: Point-to-Point Simulation Input and Fault Presets

**Files:**
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/simulation/PointToPointSimulationInputFactory.java`
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/PointToPointSimulationRequest.java`
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/PointToPointSimulationService.java`
- Test: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/PointToPointSimulationServiceTest.java`

**Interfaces:**
- Consumes: `HistoricalSimulationInput`, `HistoricalDispatchSimulator`, `SimulationConfig`, and `DeterministicFaultPlan`.
- Produces: `PointToPointSimulationInputFactory.create(HistoricalSimulationInput, String, String, DispatchTask.TaskType, int, String, List<String>)` and `PointToPointSimulationService.run(PointToPointSimulationRequest)`.

- [ ] **Step 1: Write the failing service tests**

```java
@Test
void runsOneTaskWithTheRealPlannerAndIgnoresHistoricalPath() {
    HistoricalSimulationInput base = loadBaseInput();
    HistoricalSimulationTask sample = base.getTasks().get(0);
    PointToPointSimulationRequest request = PointToPointSimulationRequest.valid(
            sample.getPhysicalSource(), sample.getPhysicalTarget(), "INBOUND", 1, 100,
            "HISTORY-CAR", Arrays.asList("WRONG", "REFERENCE"), "NONE");

    HistoricalDispatchSimulationResult result = service(base).run(request);
    SimulationTaskResult task = result.getTaskResults().get(0);

    assertEquals(SimulationTaskStatus.COMPLETED, task.getStatus());
    assertEquals(sample.getPhysicalSource(), task.getPlannedPath().get(0));
    assertEquals(sample.getPhysicalTarget(),
            task.getPlannedPath().get(task.getPlannedPath().size() - 1));
    assertFalse(task.getPlannedPath().equals(Arrays.asList("WRONG", "REFERENCE")));
    assertEquals(0, result.getInvariants().totalSafetyViolations());
}

@Test
void rejectsUnknownAndIdenticalEndpointsBeforeSimulation() {
    assertThrows(IllegalArgumentException.class, () -> service(base).run(
            PointToPointSimulationRequest.valid("UNKNOWN", validSite, "INBOUND", 1,
                    100, null, Collections.emptyList(), "NONE")));
    assertThrows(IllegalArgumentException.class, () -> service(base).run(
            PointToPointSimulationRequest.valid(validSite, validSite, "INBOUND", 1,
                    100, null, Collections.emptyList(), "NONE")));
}
```

- [ ] **Step 2: Run the focused test and confirm it fails**

Run:

```bash
mvn "-Dtest=PointToPointSimulationServiceTest" test
```

Expected: test compilation fails because the visualizer request/service/factory do not exist.

- [ ] **Step 3: Implement the request and package-local input factory**

The factory creates one `HistoricalQueueRecord` and one `HistoricalSimulationTask` with ID
`VISUALIZER-TASK-1`, current fixed simulation time, request business fields, and the base input's map,
traffic map, and initial vehicles. It validates that both sites exist and differ.

```java
public HistoricalSimulationInput create(HistoricalSimulationInput base,
                                        String sourceSite,
                                        String targetSite,
                                        DispatchTask.TaskType taskType,
                                        int priority,
                                        String historicalVehicleId,
                                        List<String> historicalPath) {
    // Construct the comparison record and one simulation task here, inside the
    // simulation package where package-private constructors are intentionally visible.
}
```

`PointToPointSimulationRequest` normalizes task type, acceleration, empty comparison fields, and
fault preset. It rejects priority outside `0..9`, acceleration other than `10/100`, and unknown enums.

- [ ] **Step 4: Implement fault presets and run the real simulator**

```java
public HistoricalDispatchSimulationResult run(PointToPointSimulationRequest request) {
    HistoricalSimulationInput input = inputFactory.create(/* normalized request fields */);
    return simulator.simulate(input,
            new SimulationConfig(request.getAcceleration(), 30_000L, 3, 200, 5_000),
            faultPlanFor(request.getFaultPreset()));
}
```

`PLC_FIRST_SEND_FAILURE` injects `SEND_FAILURE` on attempt 1 for `VISUALIZER-TASK-1`.
Vehicle presets affect all initial vehicles at tick 0 and restore/connect/synchronize at tick 2 so the
selected task actually demonstrates the requested recovery path.

- [ ] **Step 5: Run focused tests and commit**

Run:

```bash
mvn "-Dtest=PointToPointSimulationServiceTest" test
```

Expected: all focused tests pass.

Commit:

```bash
git add javaTest/src/main/java/com/ft546/wcs/shadow/history/simulation/PointToPointSimulationInputFactory.java javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/PointToPointSimulationServiceTest.java
git commit -m "feat(javaTest): add point-to-point simulation service"
```

---

### Task 2: Visualization DTO Mapping

**Files:**
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapper.java`
- Test: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapperTest.java`

**Interfaces:**
- Consumes: `HistoricalSimulationInput` and `HistoricalDispatchSimulationResult`.
- Produces: `Map<String, Object> bootstrap(HistoricalSimulationInput)` and `Map<String, Object> result(HistoricalSimulationInput, HistoricalDispatchSimulationResult)`.

- [ ] **Step 1: Write failing mapping tests**

```java
@Test
void mapsSitesTasksEventsAndSafetyEvidenceWithoutReplanning() {
    Map<String, Object> payload = mapper.result(input, result);
    List<Map<String, Object>> tasks = castList(payload.get("tasks"));
    List<Map<String, Object>> events = castList(payload.get("events"));

    assertEquals(result.getTaskResults().get(0).getPlannedPath(), tasks.get(0).get("plannedPath"));
    assertTrue(events.stream().anyMatch(event -> "ASSIGN".equals(event.get("eventType"))));
    assertTrue(events.stream().anyMatch(event -> "MOVE".equals(event.get("eventType"))));
    assertEquals(0, castMap(payload.get("invariants")).get("totalSafetyViolations"));
}

@Test
void bootstrapReturnsSortedSearchableSitesAndInitialVehicles() {
    Map<String, Object> payload = mapper.bootstrap(input);
    assertFalse(castList(payload.get("sites")).isEmpty());
    assertEquals("OFFLINE_IN_MEMORY_SIMULATION", payload.get("mode"));
}
```

- [ ] **Step 2: Run the mapping tests and confirm failure**

Run `mvn "-Dtest=SimulationVisualizationMapperTest" test`.

Expected: compilation failure because `SimulationVisualizationMapper` does not exist.

- [ ] **Step 3: Implement stable ordered JSON maps**

Use `LinkedHashMap` and sorted task/site/event lists. Include:

```text
bootstrap: mode, boundary, plannerVersion, mapSha256, floors, sites, vehicles
result: summary, tasks, events, invariants, archive, wms
task: identity, endpoints, vehicles, historicalPath, plannedPath, status, timing, holds, retries
event: tick, simulationMillis, eventType, taskId, vehicleId, reason, fromSite, toSite
site: siteId, floor, x, y, channel
```

Do not call `GridPathPlanner` from the mapper. The mapper copies the simulator result unchanged.

- [ ] **Step 4: Run mapper and existing simulator tests**

```bash
mvn "-Dtest=SimulationVisualizationMapperTest,HistoricalDispatchSimulatorTest" test
```

Expected: all selected tests pass.

- [ ] **Step 5: Commit**

```bash
git add javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapper.java javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapperTest.java
git commit -m "feat(javaTest): map simulation evidence for visualization"
```

---

### Task 3: Local HTTP Server and APIs

**Files:**
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerApplication.java`
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServer.java`
- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/VisualizerHttpException.java`
- Test: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java`

**Interfaces:**
- Consumes: Task 1 services and Task 2 mapper.
- Produces: `start()`, `stop()`, `getPort()`, `/api/health`, `/api/bootstrap`, `/api/simulations/point-to-point`, `/api/simulations/historical`, and static asset responses.

- [ ] **Step 1: Write failing HTTP contract tests**

```java
@Test
void servesHealthBootstrapAndPointToPointSimulation() throws Exception {
    server = fixture.startOnPort(0);
    assertEquals(200, get("/api/health").status);
    assertTrue(get("/api/bootstrap").body.contains("OFFLINE_IN_MEMORY_SIMULATION"));

    HttpResult response = postJson("/api/simulations/point-to-point", validRequestJson());
    assertEquals(200, response.status);
    assertTrue(response.body.contains("plannedPath"));
    assertTrue(response.body.contains("MOVE"));
}

@Test
void rejectsUnknownRoutesMethodsOversizedBodiesAndConcurrentRuns() {
    assertEquals(404, get("/api/unknown").status);
    assertEquals(405, postJson("/api/health", "{}").status);
    assertEquals(413, postJson("/api/simulations/point-to-point", oversizedBody()).status);
}
```

- [ ] **Step 2: Run the server tests and confirm failure**

Run `mvn "-Dtest=HistoricalDispatchVisualizerServerTest" test`.

Expected: compilation failure because the server classes do not exist.

- [ ] **Step 3: Implement same-origin JSON handlers**

Use a fixed thread pool with a single simulation executor and an `AtomicBoolean` busy gate. Parse and
write JSON only through the existing Jackson `ObjectMapper`. Limit request bodies before parsing.

```java
private void writeJson(HttpExchange exchange, int status, Object payload) throws IOException {
    byte[] body = objectMapper.writeValueAsBytes(payload);
    exchange.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8");
    exchange.getResponseHeaders().set("Cache-Control", "no-store");
    exchange.sendResponseHeaders(status, body.length);
    exchange.getResponseBody().write(body);
}
```

Map request failures to stable codes and never return stack traces or absolute paths.

- [ ] **Step 4: Implement the application bootstrap**

Load `shadow/history` with `HistoricalQueueLoader`, create the base input once, create services and mapper,
bind `127.0.0.1:<port>`, print the exact URL, and add a shutdown hook.

- [ ] **Step 5: Run HTTP tests and commit**

Run `mvn "-Dtest=HistoricalDispatchVisualizerServerTest" test`.

Expected: all HTTP contract tests pass and test server threads terminate.

Commit:

```bash
git add javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java
git commit -m "feat(javaTest): expose local dispatch visualizer API"
```

---

### Task 4: Operational HTML Shell and Route Playback

**Files:**
- Create: `javaTest/src/main/resources/visualizer/index.html`
- Create: `javaTest/src/main/resources/visualizer/assets/app.css`
- Create: `javaTest/src/main/resources/visualizer/assets/app.js`
- Modify: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServer.java`
- Test: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java`

**Interfaces:**
- Consumes: `/api/bootstrap` and both simulation APIs.
- Produces: a responsive first-screen audit console with stable DOM IDs used by browser QA.

- [ ] **Step 1: Extend static resource tests and confirm failure**

```java
@Test
void servesTheVisualizerShellAndAssets() throws Exception {
    assertEquals(200, get("/").status);
    assertTrue(get("/").body.contains("调度路径审计台"));
    assertEquals("text/css; charset=utf-8", get("/assets/app.css").contentType);
    assertEquals("application/javascript; charset=utf-8", get("/assets/app.js").contentType);
}
```

Run `mvn "-Dtest=HistoricalDispatchVisualizerServerTest#servesTheVisualizerShellAndAssets" test`.

Expected: 404 or missing resource failure.

- [ ] **Step 2: Build the semantic HTML shell**

Create fixed sections with IDs:

```html
<header id="app-header">...</header>
<nav id="mode-tabs" aria-label="审计模式">...</nav>
<section id="point-controls">...</section>
<main id="workspace">
  <section id="route-stage"><svg id="route-map" role="img"></svg></section>
  <aside id="task-inspector"></aside>
</main>
<section id="timeline-panel">...</section>
<section id="history-view" hidden>...</section>
<section id="safety-view" hidden>...</section>
```

The page starts as the usable tool, with no hero, marketing copy, nested cards, or decorative illustration.

- [ ] **Step 3: Implement responsive operational styling**

Use stable grid tracks, maximum 8px radius, zero negative letter spacing, and no viewport-scaled font size.
Desktop keeps the route stage dominant; under 900px it stacks controls, route, inspector, and timeline.
Use neutral surfaces plus green, blue, amber, and red semantics.

- [ ] **Step 4: Implement API state, route drawing, and tick playback**

`app.js` must:

```text
bootstrap -> populate searchable A/B datalists and metadata
run point task -> store result -> select task -> render path -> reset tick to 0
render path -> use returned site x/y/floor; draw approach, planned, and traversed layers
advance tick -> update vehicle marker, event focus, traversed edges, inspector, slider
play/pause/step -> use fixed timer and never mutate result data
```

Path coordinates use deterministic normalization with fixed SVG padding. Empty/unknown paths render an
explicit status panel instead of a blank SVG.

- [ ] **Step 5: Implement historical and safety modes**

Historical mode runs the 240-task API on command, renders KPI bands and a searchable/filterable task table,
and opens the selected task in the shared path/timeline renderer. Safety mode renders every invariant,
HOLD/retry reason distribution, archive count, and WMS idempotency. Any non-zero safety invariant changes the
global gate to `验收不通过`.

- [ ] **Step 6: Run server tests and commit**

Run:

```bash
mvn "-Dtest=HistoricalDispatchVisualizerServerTest" test
```

Expected: all static and API tests pass.

Commit:

```bash
git add javaTest/src/main/resources/visualizer javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServer.java javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java
git commit -m "feat(javaTest): add interactive dispatch audit console"
```

---

### Task 5: Documentation, Full Regression, and Browser Acceptance

**Files:**
- Modify: `javaTest/README.md`
- Create: `javaTest/src/test/resources/visualizer/point-to-point-request.json`
- Create: `javaTest/visualizer-playwright.spec.js` only if the workspace Playwright runner requires a checked-in script; otherwise keep QA scripts in a temporary workspace path.

**Interfaces:**
- Consumes: completed visualizer application.
- Produces: reproducible launch instructions, Java regression evidence, and desktop/mobile browser evidence.

- [ ] **Step 1: Document launch and safety boundary**

Add the exact Maven command, URL, three modes, route color legend, and statement that this tool is offline
evidence rather than production/HIL acceptance.

- [ ] **Step 2: Run all Java tests**

```bash
mvn clean test
```

Expected: Surefire discovers the existing 630 tests plus all new tests; Failures `0`, Errors `0`.

- [ ] **Step 3: Start the visualizer server**

```bash
mvn compile exec:java \
  -Dexec.mainClass=com.ft546.wcs.shadow.history.visualizer.HistoricalDispatchVisualizerApplication \
  -Dexec.args="18084"
```

Expected: process remains running and prints `http://127.0.0.1:18084`.

- [ ] **Step 4: Run Playwright desktop acceptance**

At `1440x900`:

```text
open page -> bootstrap succeeds -> select known source/target -> run
assert selected vehicle and planned path are visible
assert SVG has path segments and a vehicle marker
step tick -> assert marker/traversed path changes
run 240 history -> assert 240 completed, 0 waiting, 0 failed
open first task -> assert its route and events render
open safety -> assert totalSafetyViolations is 0 and WMS idempotent is true
assert browser console has no errors
save screenshot
```

- [ ] **Step 5: Run Playwright mobile and canvas-pixel acceptance**

At `390x844`, verify no overlap or horizontal overflow and save a screenshot. Sample pixels in the SVG route
area to prove the visualization is nonblank and contains multiple semantic colors.

- [ ] **Step 6: Run formatting and repository checks**

```bash
git diff --check
git status --short
```

Expected: no whitespace errors; only intentional visualizer, test, README, spec, and plan changes are present.

- [ ] **Step 7: Commit the verified result**

```bash
git add javaTest/README.md javaTest/src/main javaTest/src/test javaTest/src/main/resources/visualizer
git commit -m "docs(javaTest): document dispatch visualizer workflow"
```

Do not stage unrelated `ruoyi-admin` or `docs/*.html` changes.