# EM Planner 与 TrajectoryExecution README 设计

## 目标

为已完成的 EM Planner 首版补齐与 `CoarsePath/README.md` 一致的信息架构：

- 重写 `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md`，消除其 Foundation 阶段遗留的“LS/ST 尚未实现”描述；
- 新增 `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md`，说明滚动协调、轨迹执行和通用控制命令的职责；
- 只记录当前已实现且已验证的 API 与部署边界，不修改生产代码、测试、项目文件或插件发布脚本。

## 读者与边界

文档面向调用规划模块的上层业务与后续集成人员。它们说明如何正确准备快照、调用服务、处理失败和运行回归门禁；不提供 UI、定位、传感器、硬件控制器或动态障碍物实现指南。

两个模块的边界固定为：

```text
CoarsePath / PathSmoothing
        -> EMPlanner（纯单次规划）
        -> TrajectoryExecution（滚动协调与通用命令）
        -> future hardware adapter
```

`EmPlanningService` 继续是同步、一次性的纯规划服务。`TrajectoryExecution` 只消费调用方提供的状态和已发布的不可变轨迹，不读取 UI、硬件、系统时钟或当前工作目录。

## 文档结构

### EMPlanner README

沿用 CoarsePath 的章节风格：模块说明、文件结构、规划数据流、结果与状态、坐标和单位、最小调用示例、详细使用、验证命令、常见错误和首版限制。

它将说明 `IEmPlanningService.Plan(EmPlanningRequest, CancellationToken)` 是业务入口，调用方必须提供同版本地图/平滑路径、车辆参数、车辆状态和配置快照。只有 `Success` 或 `SuccessWithFallback` 可以消费轨迹；其他状态没有可发布的部分轨迹。

### TrajectoryExecution README

新增相同层级的模块说明、文件结构、滚动数据流、状态与安全交接、时间/单位、最小调用、详细使用、验证、常见错误和首版限制。

它将说明协调器的 latest-wins 发布、旧轨迹交接筛选、执行器的换向停稳状态机，以及 `TrajectoryControlCommand` 的带符号纵向速度、yaw rate、方向、换向请求、制动保持和完成标记。该命令是控制器中立接口；任何硬件字段映射均属于未来适配器。

## 失败与安全说明

协调器只发布完整、验证通过且身份仍为当前版本的轨迹。规划失败或过期结果不会覆盖现有发布轨迹。执行器绝不越过最后一个轨迹点外推，并在零速安全尾段持刹车。换向前必须连续满足零速停稳时间，方向请求仅发送一次，且必须等待调用方确认。

## 验证与完成标准

README 仅引用现有、从仓库根目录运行的验证入口：`em-core-all`、`coordinator`、`executor`、`plugin-package` 与 `em-all`。完成时检查两个 Markdown 文件中的相对链接、公开类型名和命令，并确认 git diff 仅包含本设计记录和两份 README。

## 明确排除

- 不实现动态障碍物、时空占用或行为决策；
- 不集成 UI、定位、传感器、底盘、电机或硬件协议；
- 不实现横移、蟹行或原地旋转；
- 不修改 LS/ST/OSQP、发布脚本、测试夹具或 `csproj`。
