# 轨迹规划全链路可视化 Demo 设计

## 目标

在 `ClumsyPilot/ParkrobTrajplanner/Trajplanner_output/trajectory-planning-flow-demo.html`
提供一个可离线打开的单页 Demo。它用一组内置的、含前进与倒车换挡的停车数据，将同一场景的地图、粗路径、平滑路径、EM 最终轨迹，以及控制层消费的轨迹采样结果放在同一可交互视图中。

Demo 的目的不是替代规划器或控制器，而是解释各阶段的输入、输出、版本身份和责任边界，并支持定位“结果为何变成当前形状”。

## 范围和非目标

### 范围

- 同坐标系地图：边界、静态障碍物、起点、终点、车辆外廓。
- 依次显示 Hybrid A* 离散粗路径、G2 平滑路径和按时间排序的 EM 轨迹点。
- 显式标记方向、换挡点和最终 `Goal` 终端。
- 通过阶段切换与时间滑块查看每阶段对应的数据流。
- 显示规划身份：`mapSnapshotId`、`referencePathId`、`VehicleMotionState.SequenceId`、轨迹 ID、`effectiveAtUtc` 与方向段编号。
- 显示控制层的最小消费边界：时间采样后的轨迹状态与 `TrajectoryControlCommand`。
- 内置示例数据、无网络请求、双击 HTML 即可运行。

### 非目标

- 不直接调用 C# 规划器、OSQP、定位、底盘或硬件协议。
- 不把控制命令伪装成真实车辆控制或安全认证功能。
- 不修改 `TrajectoryOutputDemoRunner`、现有 CSV 导出链路或任一未提交文件。

## 信息架构

页面由三个关联区域组成。

1. 阶段导航：`地图`、`粗路径`、`平滑路径`、`EM 轨迹`、`控制接口`。选择阶段会改变地图上可见的层与下方的字段说明，但底图始终保留。
2. 主地图：统一的米制局部坐标系。粗路径为离散点线，平滑路径为连续曲线，EM 轨迹显示采样点、当前时刻车辆及速度朝向；换挡点以明确文字和符号表示。
3. 数据视图：显示当前阶段的紧凑 JSON 样本与字段说明。控制接口阶段以当前轨迹点生成的通用命令为主，同时说明完整轨迹、地图和路径版本属于上游身份，而非逐周期下发字段。

## 示例数据和数据流

示例采用一个需要“前进靠近车位 → 零速换挡 → 倒车入位”的静态泊车场景。

```text
PlanningGridMap + VehicleMotionState + VehicleParameters
            │
            ▼
Hybrid A* CoarsePathResult
            │  离散姿态节点、方向、换挡点
            ▼
PathSmoothingResult
            │  连续几何、曲率、方向段
            ▼
EmPlanningResult.Success
            │  EmTrajectory（时间、位置、航向、速度、加速度、yaw rate）
            ▼
TrajectoryExecutor / TrajectoryControlAdapter
            │
            ▼
TrajectoryControlCommand
```

示例中每个阶段用小规模、相互一致的内置数组表示。地图、路径和车辆采用米；航向和 yaw rate 采用 rad / rad/s；速度采用 m/s；时间相对 `effectiveAtUtc` 表示。

## 控制边界

控制器不消费粗路径、平滑路径、走廊或优化中间量。它只消费当前、完整、已验证轨迹的采样结果，或由执行层映射得到的：

- `SignedLongitudinalVelocity`
- `YawRate`
- `Direction`
- `RequestDirectionChange`
- `HoldBrake`
- `IsTrajectoryComplete`

地图快照、参考路径 ID、车辆状态序号和轨迹 ID 会随轨迹发布和诊断保留，用于拒绝旧结果、回放和故障追踪。页面需用视觉上的“观测证据链”和“控制消费边界”分隔这两类数据，避免暗示控制层依赖中间路径。

## 交互与状态

- 初始显示完整路线概览，默认选中 `EM 轨迹`。
- 阶段切换更新叠加层、标题、字段说明与 JSON 样本。
- 时间滑块仅在 EM / 控制阶段可用；移动时更新车辆姿态、高亮轨迹点、运动字段和控制命令。
- 轨迹到达换挡点时，控制输出转为零速度、零 yaw rate、`HoldBrake=true`；确认换挡后的倒车轨迹点恢复运动命令。
- 所有交互完全局部，刷新即重置到默认示例。

## 错误表达

Demo 不模拟求解失败。页面通过固定标注强调：只有 `Success` 或 `SuccessWithFallback` 且携带完整轨迹时可进入控制输出；其他 `EmPlanningStatus` 只提供诊断，绝不作为部分轨迹下发。

## 验收标准

- HTML 在无服务器、无网络条件下能打开并完成阶段切换和轨迹回放。
- 地图叠加的粗路径、平滑路径和 EM 轨迹在一个一致坐标系内可辨认。
- 可看到至少一个换挡点及其“停车—请求换挡—确认后继续”的控制语义。
- 选择任一最终轨迹点可读到位置、航向、速度、加速度、yaw rate、段号与终端类型。
- 控制区只呈现既有 `TrajectoryControlCommand` 契约字段，且停车/完成状态强制为零速、零 yaw rate。
- 页面明确显示观测/调试证据链与控制下发契约的区别。
