diff --git a/docs/superpowers/specs/2026-08-09-trajplanner-output-demo-design.md b/docs/superpowers/specs/2026-08-09-trajplanner-output-demo-design.md new file mode 100644 index 0000000..34ce074 --- /dev/null +++ b/docs/superpowers/specs/2026-08-09-trajplanner-output-demo-design.md @@ -0,0 +1,67 @@ +# Trajplanner_output 真实轨迹输出 Demo 设计 + +## 目标 + +在 `ClumsyPilot/ParkrobTrajplanner/Trajplanner_output` 创建一个独立可运行的 .NET 控制台示例。示例从集中可调配置出发,运行 CoarsePath、PathSmoothing 与真实 OSQP 驱动的 EMPlanner,最终导出完整 `EmTrajectory.Points`,并展示控制模块如何安全读取该序列。 + +## 范围 + +- 新建 `TrajectoryOutputDemo.csproj`、程序入口、配置、运行器、CSV 导出器、控制模块只读适配器和 README。 +- 以 CoarsePath 的中文 XML 注释风格解释类型职责、单位、不变量和错误边界。 +- 输出控制台轨迹摘要和 CSV 文件;输出目录为运行时生成内容。 +- 不创建底盘、转向、制动或换向命令,不改动现有规划模块的业务逻辑。 + +## 文件结构 + +```text +Trajplanner_output/ +├── TrajectoryOutputDemo.csproj +├── Program.cs +├── TrajectoryOutputDemoConfiguration.cs +├── TrajectoryOutputDemoRunner.cs +├── TrajectorySequenceExporter.cs +├── ControlModuleTrajectoryAdapter.cs +├── README.md +└── output/ # 运行时生成,不纳入源码 +``` + +## 运行链路 + +```text +TrajectoryOutputDemoConfiguration + ▼ +PlanningMapRequest(明确允许的演示空图) + ▼ +CoarsePathPlanningService → PathSmoothingService + ▼ +EmPlanningService(new OsqpNativeSolver()) + ▼ +EmPlanningResult(仅 Success / SuccessWithFallback) + ▼ +EmTrajectory.Points + EmTrajectory.Metadata + ├── 控制台摘要 + ├── output/trajectory.csv + └── ControlModuleTrajectoryAdapter 的只读控制序列 +``` + +## 配置与输出契约 + +`TrajectoryOutputDemoConfiguration` 是唯一调参位置,覆盖地图边界、起终点、车辆尺寸、安全余量、方向、规划范围和 CSV 输出路径。世界位置和长度使用 m,航向使用 rad,速度使用 m/s,曲率使用 1/m,时间使用 s。 + +CSV 每行对应一个不可变 `EmTrajectoryPoint`,至少包含时间、X、Y、Yaw、带符号速度、YawRate、曲率、方向、方向段索引、PathS 和边界类型。元数据以控制台和单独的注释行显示,保持轨迹 ID、生效时间和终端类型可追溯。 + +`ControlModuleTrajectoryAdapter` 只将 `EmTrajectory` 投影为控制模块可读取的只读 DTO 序列;它不会向设备发送命令,也不会把世界坐标速度分量误作底盘命令。 + +## 失败与安全边界 + +- OSQP DLL 缺失、加载失败、求解失败或任一规划阶段未成功时,程序打印状态和诊断,退出为非零,不导出伪造或部分轨迹。 +- 只接受 `Success` 与 `SuccessWithFallback` 的非空轨迹;其他 `EmPlanningStatus` 都视为无输出。 +- 示例空地图只用于学习和接口演示。README 必须明确真实作业应提供有效地图障碍物来源。 +- 仅输出轨迹序列;未来控制模块应自行把带符号速度、YawRate、制动/换向确认映射到具体硬件协议。 + +## 验证 + +- 运行 `dotnet run --project ClumsyPilot/ParkrobTrajplanner/Trajplanner_output/TrajectoryOutputDemo.csproj`。 +- 成功时验证 CSV 存在、至少含一个点、时间严格递增、首行含完整字段和控制台打印轨迹 ID。 +- 若 OSQP 不可用,验证程序清晰报告真实原因并且不写成功 CSV。 +- 对 README 的路径、配置名、输出字段和命令执行静态一致性检查。