feat: 发布 EM 轨迹规划首个版本

ClumsyPilot/ParkrobTrajplanner/EMPlanner/Contracts/VehicleMotionState.cs

@@ -3,8 +3,14 @@ using MultiWheelC.TrajectoryPlanning.CoarsePath;
 
 namespace MultiWheelC.TrajectoryPlanning.EMPlanner;
 
+/// <summary>
+/// 调用方一次性捕获的车辆运动状态；EMPlanner 只消费此快照，不直接读取定位、轮速或系统时钟。
+/// </summary>
 public sealed class VehicleMotionState
 {
+    /// <summary>
+    /// 保存调用方捕获的车辆状态。构造器不校验 null、数值有限性、UTC 时效或序列号；服务在接受请求前负责验证，传入 <paramref name="pose"/> 的所有权仍归调用方。
+    /// </summary>
     public VehicleMotionState(
         Pose2D pose,
         double signedLongitudinalSpeedMetersPerSecond,
@@ -19,13 +25,28 @@ public sealed class VehicleMotionState
         SequenceId = sequenceId;
     }
 
+    /// <summary>
+    /// 车辆世界位姿引用，其中位置单位为 m、航向单位为 rad；构造器允许 null，但服务要求有效位姿。
+    /// </summary>
     public Pose2D Pose { get; }
 
+    /// <summary>
+    /// 沿车辆前向轴的有符号纵向速度，单位 m/s；正负方向约定由上游状态生产者负责，服务要求其为有限数。
+    /// </summary>
     public double SignedLongitudinalSpeedMetersPerSecond { get; }
 
+    /// <summary>
+    /// 可选的沿车辆前向轴纵向加速度，单位 m/s²；null 表示采集方未提供该量，非 null 值必须由服务验证为有限数。
+    /// </summary>
     public double? LongitudinalAccelerationMetersPerSecondSquared { get; }
 
+    /// <summary>
+    /// 采集此状态的 UTC 时刻；服务用它相对请求发起时刻判断状态是否过期。
+    /// </summary>
     public DateTimeOffset CapturedAtUtc { get; }
 
+    /// <summary>
+    /// 调用方提供的状态快照序列版本；服务要求其非负，成功轨迹将其写入元数据供消费者关联。
+    /// </summary>
     public long SequenceId { get; }
 }