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

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. 运行边界

启动入口为：

com.ft546.wcs.shadow.history.visualizer.HistoricalDispatchVisualizerApplication

启动命令为：

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 路由、请求大小限制、错误响应和串行运行门禁。所有错误统一返回：

{
  "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 回归验证

实现完成后必须运行：

mvn clean test

现有 630 项测试和新增测试必须全部由 Surefire 发现，Failures 和 Errors 均为 0。

12. 验收标准

只有同时满足以下条件才视为完成：

• 输入有效 A、B 后，页面实际调用当前 Java 调度代码并返回结果；
• 页面明确显示模拟选择车辆、接近路径、A 到 B 规划路径和逐节点轨迹；
• 路径节点都存在于完整地图且每一段均为真实邻接边；
• 可按 tick 播放全部关键调度事件；
• 可重新运行并检查 240 条历史任务；
• 完成/等待/失败、每车任务数、耗时分位数、HOLD/重试原因全部可见；
• 资源冲突、死锁、归档和 WMS 幂等结果有独立审计视图；
• 页面不连接生产系统，不发送真实设备命令；
• 自动测试和浏览器验证通过；
• 页面始终提示：离线仿真可以降低上线风险，但不能单独保证现场上线绝对无故障。