From 998f44c537feea50729634640a629d2061fdb439 Mon Sep 17 00:00:00 2001
From: zgw <13623675548@163.com>
Date: Wed, 5 Aug 2026 14:32:41 +0800
Subject: [PATCH] docs(javaTest): design dispatch visualizer

---
 ...-05-javaTest-dispatch-visualizer-design.md | 306 ++++++++++++++++++
 1 file changed, 306 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-05-javaTest-dispatch-visualizer-design.md

diff --git a/docs/superpowers/specs/2026-08-05-javaTest-dispatch-visualizer-design.md b/docs/superpowers/specs/2026-08-05-javaTest-dispatch-visualizer-design.md
new file mode 100644
index 0000000..e2bb789
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-05-javaTest-dispatch-visualizer-design.md
@@ -0,0 +1,306 @@
+# javaTest 调度过程可视化审计台设计
+
+## 1. 目标
+
+在 `javaTest` 内新增一个只绑定本机地址的离线调度审计台，让使用者能够：
+
+- 输入任意有效 A、B 物理站点，调用现有 Java 调度中心完成一次真实的单任务仿真；
+- 看到调度中心选择的车辆、车辆到 A 的接近路径、A 到 B 的服务路径和逐 tick 实际移动轨迹；
+- 运行并检查固化的 240 条真实历史任务负载；
+- 检查 HOLD、PLC 重试、清障、重新选车、完成、归档和 WMS 幂等证据；
+- 明确看到节点双占、资源超容量、对向换边、死锁等安全不变量是否为零。
+
+审计台必须复用 `HistoricalDispatchSimulator`、`GridPathPlanner`、
+`VehicleAssignmentService` 和现有交通资源组件。浏览器只负责呈现结果，不复制或改写一套
+JavaScript 调度算法。
+
+本工具属于纯内存离线仿真，不连接生产 SQL Server、PLC 或 WMS，也不作为现场 SHADOW、
+HIL、LIMITED_ACTIVE 或 ACTIVE 验收的替代品。
+
+## 2. 方案选择
+
+### 2.1 采用方案：javaTest 内置本地审计服务
+
+使用 Java 8 自带的 `com.sun.net.httpserver.HttpServer`，在 `javaTest` 进程中提供静态页面和
+JSON API。服务仅监听 `127.0.0.1`，默认端口 `18084`。
+
+采用该方案的原因：
+
+- API 直接调用现有调度代码，页面结果与自动测试使用同一实现；
+- 不引入 Spring、Node 运行时或生产后端依赖；
+- Maven 编译后即可启动，部署和排查边界清晰；
+- 可以同时支持任意 A/B 单任务和 240 条历史负载。
+
+### 2.2 不采用方案：接入 ruoyi-ui
+
+Vue、Element UI 和 ECharts 可以缩短常规管理页开发时间，但会把离线验证工具与生产前端
+耦合，还需要生产式前后端启动流程。当前目标是算法审计，不需要扩大部署边界。
+
+### 2.3 不采用方案：纯静态报告查看器
+
+纯静态页面能够读取既有报告，但无法输入任意 A/B 后调用当前 Java 算法重新执行，因此不能
+满足“亲眼检查新规划路径”的核心要求。
+
+## 3. 运行边界
+
+启动入口为：
+
+```text
+com.ft546.wcs.shadow.history.visualizer.HistoricalDispatchVisualizerApplication
+```
+
+启动命令为：
+
+```bash
+mvn compile exec:java \
+  -Dexec.mainClass=com.ft546.wcs.shadow.history.visualizer.HistoricalDispatchVisualizerApplication \
+  -Dexec.args="18084"
+```
+
+服务启动后打印准确访问地址。端口被占用时启动失败并明确提示，不静默切换到未知端口。
+
+安全边界：
+
+- 只监听 `127.0.0.1`，不对局域网或公网开放；
+- 只读取 classpath 中固化的 `shadow/history` 数据；
+- 不接受任意文件系统路径，不执行用户提供的命令；
+- POST 请求体限制为 64 KiB，仅接受已知字段、任务类型和故障预设；
+- 同一时间只允许一个仿真运行，保证确定性并避免重复占用 CPU；
+- 页面和 API 同源，不启用宽泛 CORS；
+- 默认不写报告文件，结果保存在当前浏览器会话和进程内存中。
+
+## 4. 后端模块
+
+### 4.1 `HistoricalDispatchVisualizerApplication`
+
+负责加载固化历史数据、创建共享地图上下文、启动本地 HTTP 服务并注册关闭钩子。它不包含
+业务规划逻辑。
+
+### 4.2 `HistoricalDispatchVisualizerServer`
+
+负责静态资源、HTTP 路由、请求大小限制、错误响应和串行运行门禁。所有错误统一返回：
+
+```json
+{
+  "code": "UNKNOWN_SITE",
+  "message": "起点不存在：A",
+  "details": {}
+}
+```
+
+### 4.3 `PointToPointSimulationService`
+
+把页面请求转换成一个新的 `HistoricalSimulationTask`，复用完整地图、真实车辆初始站点和现有
+仿真器。历史 `agv_id` 和 `path_info` 仅作为可选对照字段，不参与选车或规划。
+
+请求字段：
+
+- `sourceSite`：物理起点；
+- `targetSite`：物理终点；
+- `taskType`：`INBOUND`、`OUTBOUND` 或 `RELOCATION`；
+- `priority`：整数优先级；
+- `acceleration`：`10` 或 `100`；
+- `historicalVehicleId`：可选，仅用于结果对照；
+- `historicalPath`：可选，仅用于结果对照；
+- `faultPreset`：`NONE`、`PLC_FIRST_SEND_FAILURE`、`VEHICLE_RESTART`、
+  `LOW_BATTERY` 或 `DISCONNECT_RECONNECT`。
+
+未知站点返回 `UNKNOWN_SITE`；已知但不可达返回任务终态 `FAILED/NO_ROUTE`；没有当前合格车辆
+时按现有调度逻辑保持等待或由 watchdog 明确关闭，页面不伪造成功结果。
+
+### 4.4 `HistoricalWorkloadSimulationService`
+
+使用 `HistoricalSimulationInputFactory` 创建完整 240 条任务输入，并运行当前确定性故障计划。
+页面每次点击“运行 240 条”都会调用当前代码重新计算，而不是直接展示写死的成功数字。
+
+### 4.5 `SimulationVisualizationMapper`
+
+把现有结果转换为专用展示 DTO，不改变仿真对象：
+
+- 摘要、耗时分位数、HOLD/重试/失败原因；
+- 每条任务的历史/模拟车辆、历史/规划路径、状态、耗时和差异；
+- 全部 tick 事件；
+- 路径涉及站点的 `siteId/floor/x/y/channel`；
+- 归档、WMS 和安全不变量。
+
+单任务返回完整地图站点索引，页面可搜索有效站点；具体路径只返回涉及节点及相邻背景节点，
+避免一次渲染 1,175 个可通行节点造成视觉噪声。
+
+## 5. HTTP API
+
+### `GET /api/bootstrap`
+
+返回模式声明、地图版本、地图 SHA、规划器版本、车辆初始状态、楼层列表和可搜索站点列表。
+
+### `POST /api/simulations/point-to-point`
+
+运行一个任意 A/B 任务并返回任务结果、路径节点、事件、摘要和不变量。
+
+### `POST /api/simulations/historical`
+
+运行 240 条历史任务并返回完整审计结果。请求执行期间再次发起仿真返回
+`409 SIMULATION_BUSY`。
+
+### `GET /api/health`
+
+返回服务状态、地图是否加载和当前是否正在运行仿真，不连接任何外部系统。
+
+静态资源仅允许访问 `/`、`/index.html`、`/assets/app.css` 和 `/assets/app.js`。
+
+## 6. 页面信息架构
+
+第一屏直接进入调度审计工作台，不制作营销式落地页。整体为安静、紧凑的运维工具界面。
+
+### 6.1 顶部状态栏
+
+显示“离线内存仿真”、地图 SHA、规划器版本、服务状态和最近一次运行时间。离线边界始终可见，
+避免把结果误认为现场数据。
+
+### 6.2 主模式切换
+
+使用分段控件提供三个模式：
+
+1. `A → B 单任务`
+2. `240 条历史任务`
+3. `安全审计`
+
+### 6.3 A → B 单任务视图
+
+顶部是紧凑配置工具栏：可搜索起点、终点、交换按钮、任务类型、优先级、加速倍率、故障预设
+和“运行调度”按钮。
+
+主要区域分为：
+
+- 路径画布：占据最大面积，按真实 `x/y/floor` 坐标绘制；
+- 任务检查器：显示模拟车辆、历史车辆、状态、HOLD、PLC 尝试和耗时；
+- 时间线：提供播放、暂停、前一步、后一步、速度和 tick 滑块；
+- 事件表：支持按事件类型、车辆和原因过滤。
+
+### 6.4 240 条历史任务视图
+
+展示完成/等待/失败、每车完成数、重派和路径变化、平均/P95/P99 等摘要；下方为可搜索、排序、
+过滤的任务表。点击一条任务后复用同一条路径画布和时间线播放该任务。
+
+### 6.5 安全审计视图
+
+集中展示：
+
+- 节点双占；
+- 资源超容量；
+- 对向换边；
+- 死锁；
+- 重复归档；
+- WMS 重复业务效果；
+- HOLD、重试和失败原因分布；
+- 归档数、WMS 投递次数和唯一业务效果。
+
+任一安全不变量不为零时，顶部状态立即变为红色“验收不通过”，并提供对应任务和事件过滤入口。
+
+## 7. 路径可视化语义
+
+路径图必须显示真实站点编号和坐标，不能使用装饰性随机连线。
+
+- 灰色虚线：选中车辆当前位置到 A 的接近路径；
+- 绿色实线：调度中心返回的 A 到 B `plannedPath`；
+- 蓝色高亮：截至当前 tick 已实际通过的边；
+- 琥珀色：当前 HOLD 或等待资源的边/节点；
+- 红色：被拒绝或违反安全不变量的位置；
+- 空心节点：尚未经过；实心节点：已经经过；
+- A、B 和车辆当前位置使用稳定、不同的标记。
+
+`plannedPath` 直接来自 `SimulationTaskResult`。实际轨迹来自同一任务的 `MOVE` 事件。
+接近路径通过首次 `ASSIGN` 后、到达 A 之前的 `MOVE` 事件还原；若车辆初始站点就是 A，则显示
+单节点接近路径。发生重派时，按 `REDISPATCH/ASSIGN` 分段，并保留每次车辆和路线变更证据。
+
+多楼层路径按楼层切换查看；当前 tick 所在楼层自动聚焦，但不隐藏其他楼层存在路径的提示。
+等长最短路的选择遵循当前 `GridMap.getNeighbors()` 的站点编号排序，不由前端重新决定。
+
+## 8. 交互与状态
+
+- 初始态：加载站点和地图元数据，不自动运行仿真；
+- 运行态：禁用重复运行按钮，显示当前请求类型和耗时；
+- 成功态：默认停在 tick 0，由用户播放或单步检查；
+- HOLD 态：时间线暂停并突出原因，用户可继续播放；
+- 失败态：保留已产生的路径和事件，不清空证据；
+- 空结果：明确显示未知地图、无路可达或无合格车辆，不能显示空白画布；
+- 大任务态：任务表使用分页或窗口化渲染，事件列表限制可见行数；
+- 页面刷新：清除内存结果，避免把旧结果误认为新运行。
+
+键盘和鼠标均可完成播放、暂停、单步、筛选和查看任务。按钮尺寸固定，动态数字变化不能导致
+工具栏或画布跳动。桌面为主，窄屏时配置、画布、检查器和时间线纵向排列且无重叠。
+
+## 9. 视觉规范
+
+界面采用明亮中性色背景、深色正文、绿色通过状态、蓝色实际轨迹、琥珀色 HOLD 和红色失败。
+避免单一蓝色、深色大屏、渐变装饰和浮动卡片堆叠。
+
+页面区块使用全宽带状布局；卡片只用于重复任务项和确需边界的检查器。圆角不超过 8px。
+播放、暂停、单步和交换操作使用熟悉符号并提供 tooltip；明确命令使用图标加文字。
+
+## 10. 错误处理
+
+后端错误代码至少包括：
+
+- `BAD_REQUEST`
+- `UNKNOWN_SITE`
+- `SAME_ENDPOINT`
+- `INVALID_TASK_TYPE`
+- `INVALID_ACCELERATION`
+- `SIMULATION_BUSY`
+- `NO_ROUTE`
+- `WATCHDOG_DEADLOCK`
+- `TICK_LIMIT_EXCEEDED`
+- `INTERNAL_ERROR`
+
+响应不暴露本地绝对路径或堆栈。服务端记录完整异常，页面显示业务可读信息和再次运行入口。
+前端网络失败时保留上一次已完成结果并明确标记“当前服务不可用”，不得把旧结果显示为当前结果。
+
+## 11. 测试策略
+
+### 11.1 Java 自动测试
+
+- API 使用实际地图完成一个已知 A/B 单任务；
+- 返回的 `plannedPath` 首尾分别是 A、B，连续站点均为真实邻居；
+- 历史 `path_info` 改变后新路径保持不变；
+- 多辆合格车辆时返回中心调度选择结果；
+- 未知站点、相同端点、无路、busy 和错误请求返回稳定错误；
+- 240 条历史任务结果继续满足 240/0/0；
+- 所有安全不变量为零；
+- 归档和 WMS 幂等指标正确；
+- 静态资源和健康接口可访问。
+
+### 11.2 前端浏览器测试
+
+- 桌面和移动视口均无文字、工具栏、画布或时间线重叠；
+- A/B 搜索、交换、运行、播放、暂停、单步、速度和筛选均有效；
+- 路径画布包含非空真实坐标内容，并且 A、B、规划路径和车辆标记可见；
+- tick 推进时车辆标记移动，已通过路径同步高亮；
+- 历史任务列表可筛选并能打开任务详情；
+- HOLD、PLC 重试、重派、失败和安全告警状态可正确呈现；
+- 浏览器控制台无 JavaScript 错误；
+- 使用 Playwright 保存桌面与移动截图并进行画布像素检查。
+
+### 11.3 回归验证
+
+实现完成后必须运行：
+
+```bash
+mvn clean test
+```
+
+现有 630 项测试和新增测试必须全部由 Surefire 发现，Failures 和 Errors 均为 0。
+
+## 12. 验收标准
+
+只有同时满足以下条件才视为完成：
+
+- 输入有效 A、B 后，页面实际调用当前 Java 调度代码并返回结果；
+- 页面明确显示模拟选择车辆、接近路径、A 到 B 规划路径和逐节点轨迹；
+- 路径节点都存在于完整地图且每一段均为真实邻接边；
+- 可按 tick 播放全部关键调度事件；
+- 可重新运行并检查 240 条历史任务；
+- 完成/等待/失败、每车任务数、耗时分位数、HOLD/重试原因全部可见；
+- 资源冲突、死锁、归档和 WMS 幂等结果有独立审计视图；
+- 页面不连接生产系统，不发送真实设备命令；
+- 自动测试和浏览器验证通过；
+- 页面始终提示：离线仿真可以降低上线风险，但不能单独保证现场上线绝对无故障。