docs: design trajectory output demo

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