54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# 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`。
|