docs(javaTest): plan full-map route comparison

2026-08-05 16:45:30 +08:00
parent d8aeade90c
commit fad6faf949
1 changed files with 777 additions and 0 deletions
--- a/docs/superpowers/plans/2026-08-05-javaTest-full-map-route-comparison.md
+++ b/docs/superpowers/plans/2026-08-05-javaTest-full-map-route-comparison.md
@@ -0,0 +1,777 @@
+# javaTest Full-Map Route Comparison 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:** 在调度审计台中显示当前楼层完整权威地图，并在同一坐标系内清楚区分历史路径、新规划路径、共同路段和实际轨迹。
+
+**Architecture:** 新增 `RouteTopologyEvidenceMapper`，只从 `GridMap` 导出规范化无向边并计算两条路径的边集合差；`SimulationVisualizationMapper` 将这些证据加入现有 bootstrap 和 task JSON。前端使用全楼层站点计算稳定投影，缓存楼层底图，动态叠加路径比较、tick 轨迹和车辆，并通过 SVG viewBox 实现全图/聚焦、缩放和拖拽。
+
+**Tech Stack:** Java 8、JUnit 5、Jackson、Java `HttpServer`、原生 HTML/CSS/JavaScript、SVG、Playwright/Chrome 浏览器验收。
+
+## Global Constraints
+
+- 服务继续只绑定 `127.0.0.1:18084`，不连接 SQL Server、真实 PLC 或 WMS。
+- 浏览器不得实现选车或路径规划；地图边只能来自 `GridMap.getNeighbors()`。
+- 不新增 Maven 或 Node 生产依赖，保持 Java 8 编译目标。
+- 默认显示当前楼层完整地图，并保留 1-8 楼切换。
+- 新规划为绿色、历史路径为橙色点线、已通过为蓝色、HOLD 为琥珀色。
+- 共同边必须同时保留绿色底线和橙色点线证据；关闭历史参考后仍显示完整新规划。
+- 完整地图不常驻显示全部站点编号；A、B、车辆、HOLD、分叉和悬停站点可读。
+- 保留现有 `pathChanged` 节点序列语义；新增边差只用于审计解释，不参与调度结果。
+- 保留原有未跟踪 `docs/*.html`，提交时只暂存本计划列出的文件。
+
+---
+
+## File Structure
+
+- Create `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/RouteTopologyEvidenceMapper.java`: 导出完整地图边并计算路径边差。
+- Create `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/RouteTopologyEvidenceMapperTest.java`: 隔离验证规范化、集合差和无效历史段。
+- Modify `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapper.java`: 把地图边和 `pathComparison` 组装进 JSON。
+- Modify `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapperTest.java`: 验证完整真实地图数据契约。
+- Modify `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java`: 验证页面控件及 API 含完整地图证据。
+- Modify `javaTest/src/main/resources/visualizer/index.html`: 增加视口工具、差异图例和检查器字段。
+- Modify `javaTest/src/main/resources/visualizer/assets/app.css`: 完整地图、差异路径和视口交互样式。
+- Modify `javaTest/src/main/resources/visualizer/assets/app.js`: 完整楼层投影、背景缓存、差异叠加、缩放和平移。
+- Modify `javaTest/README.md`: 说明完整地图和路径对比的使用方法。
+
+---
+
+### Task 1: 权威地图边与路径差异证据模块
+
+**Files:**
+- Create: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/RouteTopologyEvidenceMapper.java`
+- Create: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/RouteTopologyEvidenceMapperTest.java`
+
+**Interfaces:**
+- Consumes: `GridMap.getSites()`、`GridMap.getNeighbors(String)`、历史与规划节点序列。
+- Produces: package-private `List<Map<String,Object>> fullMapEdges(GridMap)` 和 `Map<String,Object> compare(GridMap,List<String>,List<String>)`。
+
+- [ ] **Step 1: 写地图边与路径差异失败测试**
+
+测试构造同层站点 `A-B-C-D`、规划分支 `B-E-D`，并断言完整边唯一、共同边为 `A-B`、历史专属为 `B-C/C-D`、规划专属为 `B-E/D-E`：
+
+```java
+@Test
+void exportsCanonicalEdgesAndExplainsRouteDifferences() {
+    GridMap map = new GridMap();
+    add(map, "A", 0, 0); add(map, "B", 1, 0); add(map, "C", 2, 0);
+    add(map, "D", 3, 0); add(map, "E", 2, 1);
+    connect(map, "A", "B"); connect(map, "B", "C"); connect(map, "C", "D");
+    connect(map, "B", "E"); connect(map, "E", "D");
+
+    RouteTopologyEvidenceMapper mapper = new RouteTopologyEvidenceMapper();
+    List<Map<String, Object>> edges = mapper.fullMapEdges(map);
+    Map<String, Object> comparison = mapper.compare(map,
+            Arrays.asList("A", "B", "C", "D"),
+            Arrays.asList("A", "B", "E", "D"));
+
+    assertEquals(5, edges.size());
+    assertEquals(1, comparison.get("sharedEdgeCount"));
+    assertEquals(2, comparison.get("plannedOnlyEdgeCount"));
+    assertEquals(2, comparison.get("historicalOnlyEdgeCount"));
+    assertEquals(Collections.emptyList(), comparison.get("invalidHistoricalSegments"));
+}
+
+@Test
+void rejectsUnknownAndNonAdjacentHistoricalSegmentsWithoutInventingEdges() {
+    GridMap map = lineMap();
+    Map<String, Object> comparison = new RouteTopologyEvidenceMapper().compare(map,
+            Arrays.asList("A", "UNKNOWN", "C"), Arrays.asList("A", "B", "C"));
+
+    List<Map<String, Object>> invalid = listOfMaps(
+            comparison.get("invalidHistoricalSegments"));
+    assertEquals(2, invalid.size());
+    assertTrue(invalid.stream().allMatch(item -> "UNKNOWN_SITE".equals(item.get("reason"))));
+    assertEquals(2, comparison.get("plannedOnlyEdgeCount"));
+}
+
+private static void add(GridMap map, String id, int x, int y) {
+    map.addSite(new Site(id, 1, x, y, "TEST"));
+}
+
+private static void connect(GridMap map, String left, String right) {
+    map.connect(left, right);
+}
+
+private static GridMap lineMap() {
+    GridMap map = new GridMap();
+    add(map, "A", 0, 0); add(map, "B", 1, 0); add(map, "C", 2, 0);
+    connect(map, "A", "B"); connect(map, "B", "C");
+    return map;
+}
+
+@SuppressWarnings("unchecked")
+private static List<Map<String, Object>> listOfMaps(Object value) {
+    return (List<Map<String, Object>>) value;
+}
+```
+
+- [ ] **Step 2: 运行测试并确认 RED**
+
+Run:
+
+```powershell
+mvn "-Dtest=RouteTopologyEvidenceMapperTest" test
+```
+
+Expected: test compilation fails because `RouteTopologyEvidenceMapper` does not exist.
+
+- [ ] **Step 3: 实现最小证据映射器**
+
+实现固定接口。`EdgeKey` 对端点排序并实现 `Comparable`，所有输出使用 `TreeMap/TreeSet` 保证确定性：
+
+```java
+final class RouteTopologyEvidenceMapper {
+    List<Map<String, Object>> fullMapEdges(GridMap gridMap) {
+        requireMap(gridMap);
+        Map<EdgeKey, Map<String, Object>> edges = new TreeMap<EdgeKey, Map<String, Object>>();
+        for (String siteId : new TreeSet<String>(gridMap.getSites().keySet())) {
+            for (String neighbor : gridMap.getNeighbors(siteId)) {
+                EdgeKey key = new EdgeKey(siteId, neighbor);
+                edges.put(key, edge(gridMap, key));
+            }
+        }
+        return Collections.unmodifiableList(
+                new ArrayList<Map<String, Object>>(edges.values()));
+    }
+
+    Map<String, Object> compare(GridMap gridMap, List<String> historical,
+                                List<String> planned) {
+        requireMap(gridMap);
+        RouteEdges historicalEdges = routeEdges(gridMap, historical, true);
+        RouteEdges plannedEdges = routeEdges(gridMap, planned, false);
+        Set<EdgeKey> shared = intersection(historicalEdges.valid, plannedEdges.valid);
+        Set<EdgeKey> plannedOnly = difference(plannedEdges.valid, shared);
+        Set<EdgeKey> historicalOnly = difference(historicalEdges.valid, shared);
+        Map<String, Object> value = new LinkedHashMap<String, Object>();
+        value.put("sharedEdges", edgeMaps(gridMap, shared));
+        value.put("plannedOnlyEdges", edgeMaps(gridMap, plannedOnly));
+        value.put("historicalOnlyEdges", edgeMaps(gridMap, historicalOnly));
+        value.put("invalidHistoricalSegments", historicalEdges.invalid);
+        value.put("sharedEdgeCount", shared.size());
+        value.put("plannedOnlyEdgeCount", plannedOnly.size());
+        value.put("historicalOnlyEdgeCount", historicalOnly.size());
+        return value;
+    }
+}
+
+private static final class RouteEdges {
+    private final Set<EdgeKey> valid = new TreeSet<EdgeKey>();
+    private final List<Map<String, Object>> invalid =
+            new ArrayList<Map<String, Object>>();
+}
+
+private static final class EdgeKey implements Comparable<EdgeKey> {
+    private final String from;
+    private final String to;
+
+    private EdgeKey(String left, String right) {
+        this.from = left.compareTo(right) <= 0 ? left : right;
+        this.to = left.compareTo(right) <= 0 ? right : left;
+    }
+
+    @Override
+    public int compareTo(EdgeKey other) {
+        int fromOrder = from.compareTo(other.from);
+        return fromOrder != 0 ? fromOrder : to.compareTo(other.to);
+    }
+
+    @Override public boolean equals(Object other) {
+        return other instanceof EdgeKey && compareTo((EdgeKey) other) == 0;
+    }
+
+    @Override public int hashCode() { return 31 * from.hashCode() + to.hashCode(); }
+}
+```
+
+`routeEdges` 对每个连续节点对执行两项校验：端点必须存在；右端点必须包含在左端点的
+`getNeighbors()` 中。无效历史段写入 `{fromSite,toSite,reason}`，不得写入有效边集合。其余私有
+helper 使用以下固定签名，集合操作均返回新的 `TreeSet<EdgeKey>`，不修改输入：
+
+```java
+private RouteEdges routeEdges(GridMap map, List<String> path, boolean reportInvalid);
+private Set<EdgeKey> intersection(Set<EdgeKey> left, Set<EdgeKey> right);
+private Set<EdgeKey> difference(Set<EdgeKey> source, Set<EdgeKey> removed);
+private List<Map<String, Object>> edgeMaps(GridMap map, Set<EdgeKey> edges);
+private Map<String, Object> edge(GridMap map, EdgeKey key);
+private Map<String, Object> invalid(String from, String to, String reason);
+private void requireMap(GridMap map);
+```
+
+`edge` 固定返回 `fromSite/toSite/floor`，其中 floor 来自 `map.getSite(key.from).getFloor()`；
+`routeEdges` 对未知端点写 `UNKNOWN_SITE`，对已知但不相邻端点写 `NOT_ADJACENT`。
+
+- [ ] **Step 4: 运行单元测试并确认 GREEN**
+
+Run:
+
+```powershell
+mvn "-Dtest=RouteTopologyEvidenceMapperTest" test
+```
+
+Expected: all tests in the class pass with 0 failures and 0 errors.
+
+- [ ] **Step 5: 提交独立证据模块**
+
+```powershell
+git add -- javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/RouteTopologyEvidenceMapper.java javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/RouteTopologyEvidenceMapperTest.java
+git commit -m "feat(javaTest): map full topology and route differences"
+```
+
+---
+
+### Task 2: 将完整拓扑与路径差异加入可视化 API
+
+**Files:**
+- Modify: `javaTest/src/main/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapper.java:35-195`
+- Modify: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/SimulationVisualizationMapperTest.java:38-102`
+- Modify: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java:59-113`
+
+**Interfaces:**
+- Consumes: Task 1 的 `fullMapEdges` 与 `compare`。
+- Produces: bootstrap `edges`，task `pathComparison`，现有字段保持兼容。
+
+- [ ] **Step 1: 扩展 mapper 和 HTTP 失败测试**
+
+在 mapper 测试中从真实 `GridMap` 计算期望边数，并验证所有端点存在且无反向重复：
+
+```java
+List<Map<String, Object>> edges = listOfMaps(payload.get("edges"));
+int neighborReferences = input.getGridMap().getSites().keySet().stream()
+        .mapToInt(id -> input.getGridMap().getNeighbors(id).size()).sum();
+assertEquals(neighborReferences / 2, edges.size());
+Set<String> keys = new HashSet<String>();
+for (Map<String, Object> edge : edges) {
+    String from = String.valueOf(edge.get("fromSite"));
+    String to = String.valueOf(edge.get("toSite"));
+    assertTrue(input.getGridMap().getSites().containsKey(from));
+    assertTrue(input.getGridMap().getSites().containsKey(to));
+    assertTrue(from.compareTo(to) < 0);
+    assertTrue(keys.add(from + "|" + to));
+}
+```
+
+在仿真结果测试中验证 `pathComparison` 存在；当前 `WRONG -> REFERENCE` 历史对照应报告无效段，
+而规划路径边全部进入 `plannedOnlyEdges`。HTTP 测试增加：
+
+```java
+assertFalse(list(map(bootstrap.body).get("edges")).isEmpty());
+Map<String, Object> firstTask = map(list(map(simulation.body).get("tasks")).get(0));
+assertTrue(firstTask.containsKey("pathComparison"));
+```
+
+- [ ] **Step 2: 运行测试并确认 RED**
+
+Run:
+
+```powershell
+mvn "-Dtest=SimulationVisualizationMapperTest,HistoricalDispatchVisualizerServerTest" test
+```
+
+Expected: assertions fail because `edges` and `pathComparison` are absent.
+
+- [ ] **Step 3: 组装新证据字段**
+
+在 `SimulationVisualizationMapper` 中加入：
+
+```java
+private final RouteTopologyEvidenceMapper routeTopology =
+        new RouteTopologyEvidenceMapper();
+```
+
+`bootstrap` 在 `sites` 后写入：
+
+```java
+payload.put("edges", routeTopology.fullMapEdges(input.getGridMap()));
+```
+
+把 `task(...)` 增加 `GridMap gridMap` 参数，调用处传 `input.getGridMap()`，并在路径字段后写入：
+
+```java
+value.put("pathComparison", routeTopology.compare(
+        gridMap, historicalPath, task.getPlannedPath()));
+```
+
+不得调用 `GridPathPlanner`，不得改变 `pathChanged`、`plannedPath` 或仿真对象。
+
+- [ ] **Step 4: 运行 mapper 与 HTTP 测试并确认 GREEN**
+
+Run:
+
+```powershell
+mvn "-Dtest=RouteTopologyEvidenceMapperTest,SimulationVisualizationMapperTest,HistoricalDispatchVisualizerServerTest" test
+```
+
+Expected: all selected tests pass with 0 failures and 0 errors.
+
+- [ ] **Step 5: 提交 API 数据契约**
+
+```powershell
+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 javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java
+git commit -m "feat(javaTest): expose full-map route evidence"
+```
+
+---
+
+### Task 3: 绘制完整楼层地图与边级路径对比
+
+**Files:**
+- Modify: `javaTest/src/main/resources/visualizer/index.html:109-170`
+- Modify: `javaTest/src/main/resources/visualizer/assets/app.css:224-312`
+- Modify: `javaTest/src/main/resources/visualizer/assets/app.js:5-430`
+- Modify: `javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java:96-116`
+
+**Interfaces:**
+- Consumes: bootstrap `sites/edges` 和 task `pathComparison`。
+- Produces: `#map-fit/#path-fit/#zoom-in/#zoom-out/#reset-view` 控件、缓存的完整底图、差异路径 SVG 类和检查器计数。
+
+- [ ] **Step 1: 写静态页面契约失败测试**
+
+扩展静态资源测试：
+
+```java
+assertTrue(page.body.contains("id=\"map-fit\""));
+assertTrue(page.body.contains("id=\"path-fit\""));
+assertTrue(page.body.contains("id=\"zoom-in\""));
+assertTrue(page.body.contains("id=\"route-difference\""));
+assertTrue(stylesheet.body.contains(".map-edge"));
+assertTrue(stylesheet.body.contains(".planned-only"));
+assertTrue(stylesheet.body.contains(".historical-only"));
+assertTrue(stylesheet.body.contains(".shared-overlay"));
+```
+
+- [ ] **Step 2: 运行静态页面测试并确认 RED**
+
+Run:
+
+```powershell
+mvn "-Dtest=HistoricalDispatchVisualizerServerTest#servesTheVisualizerShellAndAssets" test
+```
+
+Expected: test fails because the full-map controls and styles are absent.
+
+- [ ] **Step 3: 增加视口工具、图例和检查器证据**
+
+在楼层选择器前后加入：
+
+```html
+<div class="view-mode" role="group" aria-label="地图视口">
+  <button id="map-fit" type="button" class="view-mode-button is-active">全图</button>
+  <button id="path-fit" type="button" class="view-mode-button">路径</button>
+</div>
+<div class="map-actions" role="group" aria-label="地图缩放">
+  <button id="zoom-out" type="button" class="icon-button" title="缩小">−</button>
+  <button id="zoom-in" type="button" class="icon-button" title="放大">＋</button>
+  <button id="reset-view" type="button" class="icon-button" title="复位视口">⌂</button>
+</div>
+```
+
+图例改为完整地图、接近路径、共同路段、仅新规划、仅历史、已通过、HOLD。检查器增加：
+
+```html
+<div><dt>路径边差</dt><dd id="route-difference">共同 -- / 新增 -- / 历史 --</dd></div>
+<div><dt>历史无效段</dt><dd id="invalid-history-segments">--</dd></div>
+```
+
+- [ ] **Step 4: 使用完整楼层坐标绘制缓存底图**
+
+在状态中加入：
+
+```javascript
+routeView: { mode: "map", x: 0, y: 0, width: 1000, height: 560 },
+routeDrag: null,
+projectors: {},
+renderedFloors: {}
+```
+
+`projectorForFloor(floor)` 必须对 `bootstrap.sites` 中该楼层全部站点计算一次稳定投影。底图只从
+`bootstrap.edges` 取当前楼层真实边：
+
+```javascript
+function projectorForFloor(floor) {
+  if (state.projectors[floor]) return state.projectors[floor];
+  var sites = state.bootstrap.sites.filter(function (site) { return site.floor === floor; });
+  var xs = sites.map(function (site) { return Number(site.x); });
+  var ys = sites.map(function (site) { return Number(site.y); });
+  var minX = Math.min.apply(Math, xs), maxX = Math.max.apply(Math, xs);
+  var minY = Math.min.apply(Math, ys), maxY = Math.max.apply(Math, ys);
+  var width = Math.max(1, maxX - minX), height = Math.max(1, maxY - minY);
+  var scale = Math.min(880 / width, 440 / height);
+  var offsetX = (1000 - width * scale) / 2;
+  var offsetY = (560 - height * scale) / 2;
+  state.projectors[floor] = function (site) {
+    if (!site || site.floor !== floor) return null;
+    return { x: offsetX + (Number(site.x) - minX) * scale,
+      y: 560 - offsetY - (Number(site.y) - minY) * scale };
+  };
+  return state.projectors[floor];
+}
+
+function renderMapBackground(floor, projector) {
+  var cache = elements["route-map"].querySelector("#map-cache-layer");
+  var id = "map-floor-" + floor;
+  var layer = cache.querySelector("#" + id);
+  if (!layer) {
+    layer = svgElement("g", { id: id, class: "map-floor-layer" });
+    state.bootstrap.edges.filter(function (edge) { return edge.floor === floor; })
+      .forEach(function (edge) {
+        drawSegment(layer, edge.fromSite, edge.toSite, "map-edge", projector);
+      });
+    state.bootstrap.sites.filter(function (site) { return site.floor === floor; })
+      .forEach(function (site) { drawBackgroundNode(layer, site, projector); });
+    cache.appendChild(layer);
+  }
+  cache.querySelectorAll(".map-floor-layer").forEach(function (item) {
+    item.hidden = item.id !== id;
+  });
+}
+
+function drawBackgroundNode(layer, site, projector) {
+  var point = projector(site);
+  if (!point) return;
+  var node = svgElement("circle", {
+    cx: point.x, cy: point.y, r: 2.4, class: "map-site"
+  });
+  var title = svgElement("title");
+  title.textContent = site.siteId + " · " + site.floor + "F · (" +
+    site.x + ", " + site.y + ")";
+  node.appendChild(title);
+  layer.appendChild(node);
+}
+```
+
+SVG 内固定使用 `map-cache-layer` 和 `dynamic-route-layer`。没有任务时不再用不透明空状态盖住底图。
+
+- [ ] **Step 5: 按 `pathComparison` 分层叠加差异路径**
+
+```javascript
+function drawRouteComparison(layer, task, projector) {
+  var comparison = task.pathComparison;
+  drawEvidenceEdges(layer, comparison.sharedEdges, "shared-base planned-only", projector);
+  if (elements["show-historical"].checked) {
+    drawEvidenceEdges(layer, comparison.sharedEdges,
+      "shared-overlay historical-only", projector);
+    drawEvidenceEdges(layer, comparison.historicalOnlyEdges,
+      "historical-only", projector);
+  }
+  drawEvidenceEdges(layer, comparison.plannedOnlyEdges, "planned-only", projector);
+}
+
+function comparisonNodeIds(task) {
+  var comparison = task.pathComparison;
+  var values = [];
+  [].concat(comparison.plannedOnlyEdges, comparison.historicalOnlyEdges)
+    .forEach(function (edge) { values.push(edge.fromSite, edge.toSite); });
+  return new Set(values);
+}
+
+function drawEvidenceEdges(layer, edges, className, projector) {
+  edges.forEach(function (edge) {
+    drawSegment(layer, edge.fromSite, edge.toSite, className, projector);
+  });
+}
+```
+
+接近路径继续为灰色虚线，MOVE 继续为蓝色，二者位于比较路径之上。检查器从
+`task.pathComparison` 显示三类计数及无效历史段文本。动态路径节点的 `label` 条件改为
+`start || target || hold || siteId === currentSite || comparisonNodeIds(task).has(siteId)`，不再按节点
+总数周期性显示文字。
+
+`renderRoute` 的入口顺序固定为先绘制底图、再判断任务是否存在，确保页面初始化时完整地图可见：
+
+```javascript
+function renderRoute() {
+  if (!state.bootstrap || state.selectedFloor === null) return;
+  var projector = projectorForFloor(state.selectedFloor);
+  renderMapBackground(state.selectedFloor, projector);
+  clearDynamicRouteLayer();
+  var task = selectedTask();
+  if (!task) {
+    showMapHint("等待调度结果", "完整地图已加载");
+    applyRouteView();
+    return;
+  }
+  hideMapHint();
+  renderTaskRoute(task, projector);
+  applyRouteView();
+}
+```
+
+`loadBootstrap` 在填充站点后把 `state.selectedFloor` 设置为 `bootstrap.floors[0]`，填充楼层下拉并
+调用 `renderRoute()`；`clearDynamicRouteLayer/renderTaskRoute/showMapHint/hideMapHint` 分别只负责
+删除动态组、绘制任务叠加、显示非遮罩提示和隐藏提示，禁止清除 `map-cache-layer`。
+
+- [ ] **Step 6: 添加底图与差异路径 CSS**
+
+```css
+.map-edge { stroke: #cfd7d4; stroke-width: 1.25; opacity: .82; }
+.map-site { fill: #d7dedb; stroke: #b8c3bf; stroke-width: 1; }
+.route-segment.planned-only { stroke: var(--color-service-path); stroke-width: 6; }
+.route-segment.historical-only { stroke: var(--color-historical-path); stroke-width: 4; stroke-dasharray: 3 7; }
+.route-segment.shared-base { stroke: var(--color-service-path); stroke-width: 7; }
+.route-segment.shared-overlay { stroke: var(--color-historical-path); stroke-width: 3; stroke-dasharray: 2 8; }
+#route-map.is-pannable { cursor: grab; touch-action: none; }
+#route-map.is-dragging { cursor: grabbing; }
+```
+
+- [ ] **Step 7: 运行页面与 API 测试并确认 GREEN**
+
+Run:
+
+```powershell
+mvn "-Dtest=HistoricalDispatchVisualizerServerTest,SimulationVisualizationMapperTest" test
+```
+
+Expected: all selected tests pass, shell contains new controls, API still returns real planned path.
+
+- [ ] **Step 8: 提交完整地图静态视图**
+
+```powershell
+git add -- javaTest/src/main/resources/visualizer/index.html javaTest/src/main/resources/visualizer/assets/app.css javaTest/src/main/resources/visualizer/assets/app.js javaTest/src/test/java/com/ft546/wcs/shadow/history/visualizer/HistoricalDispatchVisualizerServerTest.java
+git commit -m "feat(javaTest): render full-map route comparison"
+```
+
+---
+
+### Task 4: 全图/路径适配、缩放、拖拽与楼层状态
+
+**Files:**
+- Modify: `javaTest/src/main/resources/visualizer/assets/app.js:48-75,240-530`
+- Modify: `javaTest/src/main/resources/visualizer/assets/app.css:232-405`
+
+**Interfaces:**
+- Consumes: Task 3 的稳定楼层 projector 和 SVG 分层。
+- Produces: 视口模式、viewBox 缩放平移、楼层路径提示和 tick 稳定视口。
+
+- [ ] **Step 1: 绑定完整视口交互**
+
+```javascript
+elements["map-fit"].addEventListener("click", function () { setViewMode("map"); });
+elements["path-fit"].addEventListener("click", function () { setViewMode("path"); });
+elements["zoom-in"].addEventListener("click", function () { zoomRoute(0.8); });
+elements["zoom-out"].addEventListener("click", function () { zoomRoute(1.25); });
+elements["reset-view"].addEventListener("click", resetRouteView);
+elements["route-map"].addEventListener("wheel", handleRouteWheel, { passive: false });
+elements["route-map"].addEventListener("pointerdown", beginRouteDrag);
+window.addEventListener("pointermove", continueRouteDrag);
+window.addEventListener("pointerup", endRouteDrag);
+```
+
+- [ ] **Step 2: 使用 viewBox 实现适配、缩放和平移**
+
+```javascript
+function applyRouteView() {
+  var view = state.routeView;
+  elements["route-map"].setAttribute("viewBox",
+    [view.x, view.y, view.width, view.height].join(" "));
+}
+
+function zoomRoute(factor, anchorX, anchorY) {
+  var view = state.routeView;
+  var nextWidth = Math.max(160, Math.min(1600, view.width * factor));
+  var nextHeight = nextWidth * 0.56;
+  var xRatio = anchorX === undefined ? 0.5 : anchorX;
+  var yRatio = anchorY === undefined ? 0.5 : anchorY;
+  view.x += (view.width - nextWidth) * xRatio;
+  view.y += (view.height - nextHeight) * yRatio;
+  view.width = nextWidth;
+  view.height = nextHeight;
+  applyRouteView();
+}
+
+function resetRouteView() {
+  state.routeView = { mode: "map", x: 0, y: 0, width: 1000, height: 560 };
+  updateViewModeButtons();
+  applyRouteView();
+}
+
+function selectedRouteSiteIds() {
+  var task = selectedTask();
+  if (!task) return [];
+  var ids = [].concat(task.plannedPath || [], task.historicalPath || [],
+    [task.physicalStartSite, task.physicalEndSite]);
+  eventsForTask(currentResult(), task.simulationTaskId).forEach(function (event) {
+    if (event.fromSite) ids.push(event.fromSite);
+    if (event.toSite) ids.push(event.toSite);
+  });
+  return ids;
+}
+
+function setViewMode(mode) {
+  if (mode === "map") resetRouteView();
+  else fitPathView(selectedRouteSiteIds(), projectorForFloor(state.selectedFloor));
+  state.routeView.mode = mode;
+  updateViewModeButtons();
+}
+
+function handleRouteWheel(event) {
+  event.preventDefault();
+  var rect = elements["route-map"].getBoundingClientRect();
+  zoomRoute(event.deltaY > 0 ? 1.12 : 0.89,
+    (event.clientX - rect.left) / rect.width,
+    (event.clientY - rect.top) / rect.height);
+}
+
+function beginRouteDrag(event) {
+  state.routeDrag = { x: event.clientX, y: event.clientY };
+  elements["route-map"].classList.add("is-dragging");
+}
+
+function continueRouteDrag(event) {
+  if (!state.routeDrag) return;
+  var rect = elements["route-map"].getBoundingClientRect();
+  state.routeView.x -= (event.clientX - state.routeDrag.x) *
+    state.routeView.width / rect.width;
+  state.routeView.y -= (event.clientY - state.routeDrag.y) *
+    state.routeView.height / rect.height;
+  state.routeDrag = { x: event.clientX, y: event.clientY };
+  applyRouteView();
+}
+
+function endRouteDrag() {
+  state.routeDrag = null;
+  elements["route-map"].classList.remove("is-dragging");
+}
+
+function updateViewModeButtons() {
+  elements["map-fit"].classList.toggle("is-active", state.routeView.mode === "map");
+  elements["path-fit"].classList.toggle("is-active", state.routeView.mode === "path");
+}
+```
+
+`fitPathView` 对当前楼层的历史、规划、接近、MOVE、A/B 和车辆节点求 SVG 坐标包围盒，并增加
+最少 48 SVG 单位边距。`setViewMode("map")` 设置 `0 0 1000 560`；推进 tick 只调用动态绘制，
+不得调用 `resetRouteView`。
+
+```javascript
+function fitPathView(siteIds, projector) {
+  var points = unique(siteIds).map(siteById).filter(Boolean).map(projector).filter(Boolean);
+  if (!points.length) { resetRouteView(); return; }
+  var xs = points.map(function (point) { return point.x; });
+  var ys = points.map(function (point) { return point.y; });
+  var padding = 48;
+  var minX = Math.max(0, Math.min.apply(Math, xs) - padding);
+  var minY = Math.max(0, Math.min.apply(Math, ys) - padding);
+  var maxX = Math.min(1000, Math.max.apply(Math, xs) + padding);
+  var maxY = Math.min(560, Math.max.apply(Math, ys) + padding);
+  var width = Math.max(160, maxX - minX);
+  var height = Math.max(90, maxY - minY);
+  var ratio = 1000 / 560;
+  if (width / height > ratio) height = width / ratio;
+  else width = height * ratio;
+  state.routeView = { mode: "path", x: minX, y: minY, width: width, height: height };
+  applyRouteView();
+}
+```
+
+- [ ] **Step 3: 让楼层选项表达路径和车辆状态**
+
+`populateFloors` 始终列出 bootstrap 的 1-8 楼，选项文字规则固定为：
+
+```javascript
+var suffix = floor === vehicleFloor ? " · 车辆" : pathFloors.has(floor) ? " · 路径" : "";
+option.textContent = floor + "F" + suffix;
+```
+
+首次任务结果选择起点楼层；车辆跨层后只更新提示，不强制打断用户正在查看的楼层。用户切换楼层
+时按当前 `routeView.mode` 重新适配。
+
+- [ ] **Step 4: 用浏览器执行交互验收**
+
+启动服务：
+
+```powershell
+mvn compile exec:java "-Dexec.mainClass=com.ft546.wcs.shadow.history.visualizer.HistoricalDispatchVisualizerApplication" "-Dexec.args=18084"
+```
+
+Playwright 脚本必须断言：
+
+```javascript
+const mapEdges = await page.locator(
+  "#map-cache-layer .map-floor-layer:not([hidden]) .map-edge").count();
+const planned = await page.locator("#dynamic-route-layer .planned-only").count();
+check(mapEdges > planned, "full map was not rendered");
+await page.locator("#path-fit").click();
+const focusedViewBox = await page.locator("#route-map").getAttribute("viewBox");
+await page.locator("#map-fit").click();
+check(focusedViewBox !== await page.locator("#route-map").getAttribute("viewBox"),
+      "map/path fit did not change the viewport");
+check(await page.locator("#dynamic-route-layer .historical-only").count() > 0,
+      "historical-only route evidence is missing");
+```
+
+同时验证滚轮后 viewBox 改变、拖拽后 x/y 改变、tick 推进后 viewBox 不变、关闭历史参考后绿色
+规划仍存在、1440x900 与 390x844 无页面横向溢出、浏览器控制台无错误。保存完整地图、路径聚焦、
+安全页和移动端截图，并人工检查路径与底图非空且不遮挡。
+
+- [ ] **Step 5: 提交视口交互**
+
+```powershell
+git add -- javaTest/src/main/resources/visualizer/assets/app.js javaTest/src/main/resources/visualizer/assets/app.css
+git commit -m "feat(javaTest): add route map viewport controls"
+```
+
+---
+
+### Task 5: 文档、全量回归与最终运行
+
+**Files:**
+- Modify: `javaTest/README.md:99-130`
+
+**Interfaces:**
+- Consumes: 完整地图页面最终行为。
+- Produces: 可重复启动和人工核查说明、最终绿色工作树证据。
+
+- [ ] **Step 1: 更新 README 使用说明**
+
+在审计页面章节加入：
+
+```markdown
+地图默认显示当前楼层完整拓扑。“全图”用于判断路径位于实际地图的通道位置，“路径”用于放大
+查看分叉细节。绿色是新规划，橙色点线是历史参考；两者重合时绿色底线上保留橙色点线。
+检查器分别统计共同边、仅新规划边、仅历史边，并报告无法映射到当前完整地图的历史段。
+```
+
+- [ ] **Step 2: 运行全量 Maven 回归**
+
+Run:
+
+```powershell
+mvn clean test
+```
+
+Expected: Surefire discovers more than 642 tests; failures 0, errors 0, skipped 0.
+
+- [ ] **Step 3: 检查补丁和工作树边界**
+
+Run:
+
+```powershell
+git diff --check
+git status --short
+```
+
+Expected: `git diff --check` exits 0；状态只包含本计划文件或原有未跟踪 `docs/*.html`，后者不暂存。
+
+- [ ] **Step 4: 最终浏览器复验**
+
+重新运行 Task 4 的 Playwright 验收，并额外执行 240 条历史任务，断言完成 240、等待 0、失败 0、
+安全失败门禁 0、归档 240/240、WMS 幂等、页面控制台无错误。
+
+- [ ] **Step 5: 提交文档**
+
+```powershell
+git add -- javaTest/README.md
+git commit -m "docs(javaTest): explain full-map route audit"
+```
+
+- [ ] **Step 6: 留下可访问的本地服务**
+
+启动 `HistoricalDispatchVisualizerApplication` 并验证：
+
+```powershell
+Invoke-WebRequest -UseBasicParsing http://127.0.0.1:18084/api/health
+```
+
+Expected: HTTP 200，JSON 包含 `"status":"UP"`、`"mapLoaded":true` 和
+`"simulationBusy":false`。最终向使用者提供 `http://127.0.0.1:18084`。