docs: document trajectory execution contracts

ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs

@@ -3,12 +3,14 @@ using MultiWheelC.TrajectoryPlanning.CoarsePath;
 
 namespace MultiWheelC.TrajectoryPlanning.EMPlanner;
 
+/// <summary>下一轮规划起点的来源；只允许安全未来样本或调用方测量状态二选一。</summary>
 public enum TrajectoryHandoffSource
 {
     MeasuredState,
     PreviousTrajectory,
 }
 
+/// <summary>拒绝使用已发布轨迹进行交接的稳定原因；拒绝时必须回退到测量状态。</summary>
 public enum TrajectoryHandoffRejectionReason
 {
     None,
@@ -25,7 +27,7 @@ public enum TrajectoryHandoffRejectionReason
     SampleUnavailable,
 }
 
-/// <summary>Immutable handoff decision for the next one-shot planning request.</summary>
+/// <summary>下一次单次规划的不可变交接决策；不会跨方向段、方向或终端边界复用旧轨迹。</summary>
 public sealed class TrajectoryHandoffSelection
 {
     internal TrajectoryHandoffSelection(TrajectoryHandoffSource source, VehicleMotionState startState,
@@ -38,6 +40,7 @@ public sealed class TrajectoryHandoffSelection
         RejectionReason = rejectionReason;
     }
 
+    /// <summary>交接使用未来旧轨迹样本还是调用方测量状态。</summary>
     public TrajectoryHandoffSource Source { get; }
 
     public VehicleMotionState StartState { get; }
@@ -49,12 +52,13 @@ public sealed class TrajectoryHandoffSelection
     public TrajectoryHandoffRejectionReason RejectionReason { get; }
 }
 
-/// <summary>Selects a future same-segment seed or preserves the caller's measured state.</summary>
+/// <summary>选择安全的同段同方向未来轨迹种子；任一检查失败时保留调用方测量状态。</summary>
 public sealed class TrajectoryHandoffSelector
 {
     private const double TimeEpsilonSeconds = 1e-9d;
     private readonly TrajectorySampler sampler;
 
+    /// <summary>使用默认同质区间采样器创建交接选择器。</summary>
     public TrajectoryHandoffSelector()
         : this(new TrajectorySampler())
     {
@@ -65,6 +69,14 @@ public sealed class TrajectoryHandoffSelector
         this.sampler = sampler ?? throw new ArgumentNullException(nameof(sampler));
     }
 
+    /// <summary>从已发布轨迹选择下一轮规划的未来交接状态。</summary>
+    /// <param name="previousTrajectory">最后一条完整已发布轨迹；为 <see langword="null"/> 时直接使用测量状态。</param>
+    /// <param name="measuredState">调用方当前车辆状态快照；位置 m、航向 rad、带符号速度 m/s。</param>
+    /// <param name="expectedSegmentIndex">下一轮请求期望的非负方向段索引。</param>
+    /// <param name="expectedDirection">下一轮请求期望的实际行驶方向。</param>
+    /// <param name="now">调用方当前时刻，用于检查旧轨迹年龄和 lookahead。</param>
+    /// <param name="configuration">包含最大状态年龄、lookahead 和追踪容差的配置快照。</param>
+    /// <returns>只有年龄、追踪、同段同方向、末点和边界检查均通过时返回未来轨迹样本；否则返回测量状态及拒绝原因。</returns>
     public TrajectoryHandoffSelection Select(EmTrajectory previousTrajectory, VehicleMotionState measuredState,
         int expectedSegmentIndex, TravelDirection expectedDirection, DateTimeOffset now,
         EmPlannerConfiguration configuration)