docs: correct EM controller handoff guide

2026-08-11 17:31:46 +08:00
parent ccf795dea4
commit c17a6edd25
3 changed files with 50 additions and 19 deletions
@@ -21,7 +21,7 @@ PlanningGridMap → PlanningRequest → HybridAStarPlanner.Plan
 → EmControlTrajectoryAdapter.Create → Trajectory2D → TrajectoryTrackingMovement
 ```

-路径、地图和车辆参数使用 SI：世界位置为 m，航向为 rad，曲率为 1/m。`PlanningGridMap` 是冻结地图快照；不要把 Clumsy 绘图用的 mm 坐标直接交给规划器。
+路径、位姿、车辆和轨迹值使用 SI：世界位置为 m，航向为 rad，曲率为 1/m。地图输入是明确的例外：`PlanningMapRequest` / `MapBoundsMm` 的边界、`ResolutionMm` 和障碍物几何均使用世界 mm，如完整示例步骤 3 所示。`PlanningGridMap` 是该 mm 地图请求生成的冻结快照。只能在明确拥有的边界做 m/mm 转换并保留单位标注：不得把 Clumsy 的 mm 坐标直接交给 `Pose2D`，也不得把 m 值未转换就交给 mm 地图契约；单位不明时立即停止，不根据数值大小猜测。

 ## 步骤 1–15

@@ -49,7 +49,7 @@ PlanningGridMap → PlanningRequest → HybridAStarPlanner.Plan

 [对应完整示例：步骤 3](EmPlannerFullPipelineDemo.cs#L84)

-**本步输入**：固定障碍物、地图边界与栅格分辨率。
+**本步输入**：固定障碍物、`MapBoundsMm` 地图边界与 `ResolutionMm` 栅格分辨率；这些地图几何值均为世界 mm。
 **调用**：建立并冻结 `PlanningGridMap`。
 **本步输出**：同一 `SnapshotId` 的可读地图。
 **失败处理**：地图未就绪、起点或终点越界/碰撞时拒绝，不生成替代移动命令。
@@ -214,13 +214,13 @@ Trajectory2D controllerTrajectory =
 | `VelocityX`, `VelocityY` | 世界 m/s | 由有符号速度和航向导出的预测分量。`VelocityX` 和 `VelocityY` 是世界坐标系中的预测速度分量，不是底盘纵向/横向命令；闭环测试不得把它们直接发送给车辆。 |
 | `YawRate` | rad/s | `SignedLongitudinalVelocity * VehicleCurvature` 导出的预测偏航角速度。 |
 | `SegmentIndex`, `SegmentLocalS`, `PathS`, `Direction`, `BoundaryType` | 索引、m、m、枚举、枚举 | 段归属、局部/全路径弧长、方向及目标/换向边界；用于保证不跨方向消费。 |
-| `LongitudinalAcceleration`, `LongitudinalJerk` | m/s²、m/s³ | 沿车体前向轴的规划量；当前为程序集内部验证/执行成员，不是 `Trajectory2D` 输入。 |
+| `LongitudinalAcceleration`, `LongitudinalJerk` | m/s²、m/s³ | 沿车体前向轴的规划器内部诊断量，不是 `Trajectory2D` 输入。外部维护者不得复制对内部成员的访问；如自有构建确需该证据，必须先通过其显式公开契约暴露后再读取。 |

 VelocityX 和 VelocityY 是世界坐标系中的预测速度分量，不是底盘纵向/横向命令；闭环测试不得把它们直接发送给车辆。

 | 概念 | 正确解释 | 常见错误 |
 | --- | --- | --- |
-| m / mm | 规划与 `Trajectory2D` 均为 m；外部测试仅绘图时将 m 乘 1000。 | 将 Clumsy `Vector2` 的 mm 直接用于 `Pose2D`。 |
+| m / mm | 路径、`Pose2D`、车辆和 `EmTrajectory` / `Trajectory2D` 值为 SI m；`PlanningMapRequest` / `MapBoundsMm` 边界、`ResolutionMm` 和障碍几何为世界 mm。仅在明确的接口边界转换。 | 将 Clumsy `Vector2` 的 mm 直接用于 `Pose2D`，或将 m 障碍几何直接填入 mm 地图契约。 |
 | rad / deg | 所有 `Yaw`、转角、容差为 rad；`AngleMath.DegreesToRadians` 只用于初始化控制器角度。 | 将 3 或 45 当作 rad。 |
 | 1/m、m/s、m/s²、m/s³、rad/s | 分别是曲率、速度、加速度、jerk、偏航角速度。 | 用曲率替代转向角，或把加速度当速度。 |
 | 世界/车体 | `X/Y/Yaw`、`VelocityX/Y` 在世界系；有符号纵向速度、加速度、jerk 沿车体前向轴。 | 把世界 XY 分量作为车体纵/横向命令。 |
@@ -302,11 +302,11 @@ VelocityX 和 VelocityY 是世界坐标系中的预测速度分量，不是底
 | 方向不匹配 | `StateDirectionMismatch`，或 Metadata/点方向不同 | 只用当前活动段；先停稳再重新确认。 |
 | 适配器拒绝 | 少于两个不同位置点，`Create` 抛出 | 不修改原始轨迹硬凑点；修复上游输出。 |

-本 demo 是**单方向**。换向需要在当前段的精确边界完整停车，并在安全审查后的换向状态机确认下一方向后，单独请求并执行下一段规划。不得把正、负方向段串接成一个 `Trajectory2D`，也不得跨换向边界插值。
+本 demo 是**单方向**。有效的 `FullDirectionSegment` 轨迹即使以 `EmTerminalType.GearSwitch` 结束，仍只是一个可跟踪到精确停车的安全方向段；但调用方只能在显式提供已通过安全评审的换向交接授权时执行该段。授权仅覆盖“执行当前段并在换向边界精确停车”；到站后必须由外部状态机确认已停稳和下一方向，然后单独请求并执行下一段。授权绝不允许把正、负方向点串接成一个 `Trajectory2D`、自动跨越边界或跨边界插值。

 ## 外部闭环测试中的替换点

-当前应替换的人工来源是外部 `NewControllerTrackingTests.cs` 中的 `TestTrajectoryFactory.CreateStraight4Meters`（在直线 4 m 测试中构造 `trajectory`）。下游汇是 `TrajectoryTrackingMovement.Trajectory`。合并时只把该变量的来源替换为本指南的服务调用和适配器输出；`StateProvider`、Stanley/PID/GCP 调参、完成/偏离保护、超时与记录器均由控制器测试继续拥有。不要改写它们来迁就规划器。
+当前应替换的人工来源是外部 `NewControllerTrackingTests.cs` 中的 `TestTrajectoryFactory.CreateStraight4Meters`（在直线 4 m 测试中构造 `trajectory`）。下游汇是 `TrajectoryTrackingMovement.Trajectory`。合并时只把该变量的来源替换为本指南的服务调用和适配器输出；`StateProvider`、Stanley/PID/GCP 调参、完成/偏离保护、超时与记录器均由控制器测试继续拥有。包装器和直接服务替换路径都要求调用方显式传入换向交接是否已通过安全评审和授权；未授权的 `GearSwitch` 轨迹必须在创建跟踪动作前拒绝。不要改写原有安全所有权来迁就规划器。

 ## 建议阅读顺序