ParkingRobot/docs/superpowers/specs/2026-08-09-trajplanner-output-demo-design.md

Trajplanner_output 真实轨迹输出 Demo 设计

目标

在 ClumsyPilot/ParkrobTrajplanner/Trajplanner_output 创建一个独立可运行的 .NET 控制台示例。示例从集中可调配置出发，运行 CoarsePath、PathSmoothing 与真实 OSQP 驱动的 EMPlanner，最终导出完整 EmTrajectory.Points，并展示控制模块如何安全读取该序列。

范围

• 新建 TrajectoryOutputDemo.csproj、程序入口、配置、运行器、CSV 导出器、控制模块只读适配器和 README。
• 以 CoarsePath 的中文 XML 注释风格解释类型职责、单位、不变量和错误边界。
• 输出控制台轨迹摘要和 CSV 文件；输出目录为运行时生成内容。
• 不创建底盘、转向、制动或换向命令，不改动现有规划模块的业务逻辑。

文件结构

Trajplanner_output/
├── TrajectoryOutputDemo.csproj
├── Program.cs
├── TrajectoryOutputDemoConfiguration.cs
├── TrajectoryOutputDemoRunner.cs
├── TrajectorySequenceExporter.cs
├── ControlModuleTrajectoryAdapter.cs
├── README.md
└── output/                         # 运行时生成，不纳入源码

运行链路

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 的路径、配置名、输出字段和命令执行静态一致性检查。