778 lines
31 KiB
Markdown
778 lines
31 KiB
Markdown
# 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`。
|