docs: document trajectory execution contracts

ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleIdentity.cs

@@ -2,9 +2,15 @@ using System;
 
 namespace MultiWheelC.TrajectoryPlanning.EMPlanner;
 
-/// <summary>Immutable identity bound to one rolling planning cycle.</summary>
+/// <summary>绑定一次滚动周期的不可变版本身份；所有字段必须同时匹配，旧结果才可发布。</summary>
 public sealed class PlanningCycleIdentity : IEquatable<PlanningCycleIdentity>
 {
+    /// <summary>创建完整周期身份。</summary>
+    /// <param name="mapSnapshotId">规划地图快照的非负版本 ID。</param>
+    /// <param name="referencePathId">平滑参考路径的非空版本 ID。</param>
+    /// <param name="vehicleStateSequenceId">调用方捕获的车辆状态非负序列号。</param>
+    /// <param name="previousTrajectoryId">上一条轨迹 ID；没有时使用空字符串。</param>
+    /// <param name="segmentIndex">当前前进或倒车方向段的非负索引。</param>
     public PlanningCycleIdentity(long mapSnapshotId, string referencePathId, long vehicleStateSequenceId,
         string previousTrajectoryId, int segmentIndex)
     {
@@ -24,6 +30,7 @@ public sealed class PlanningCycleIdentity : IEquatable<PlanningCycleIdentity>
         SegmentIndex = segmentIndex;
     }
 
+    /// <summary>规划地图快照版本 ID。</summary>
     public long MapSnapshotId { get; }
 
     public string ReferencePathId { get; }
@@ -34,6 +41,9 @@ public sealed class PlanningCycleIdentity : IEquatable<PlanningCycleIdentity>
 
     public int SegmentIndex { get; }
 
+    /// <summary>从已冻结的 EM 请求派生发布身份。</summary>
+    /// <param name="request">必须携带地图和车辆状态快照的 EM 请求。</param>
+    /// <returns>包含请求地图、路径、状态、上一轨迹和方向段字段的不可变身份。</returns>
     public static PlanningCycleIdentity FromRequest(EmPlanningRequest request)
     {
         if (request == null)