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