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

ClumsyPilot/ParkrobTrajplanner/EMPlanner/Contracts/EmTrajectoryMetadata.cs

@@ -3,8 +3,14 @@ using MultiWheelC.TrajectoryPlanning.CoarsePath;
 
 namespace MultiWheelC.TrajectoryPlanning.EMPlanner;
 
+/// <summary>
+/// 轨迹发布身份、来源版本、有效时间、方向段和终端边界的不可变元数据。
+/// </summary>
 public sealed class EmTrajectoryMetadata
 {
+    /// <summary>
+    /// 创建轨迹的发布和来源元数据。验证标识、序列号、索引和枚举值；<paramref name="previousTrajectoryId"/> 可为 null 并会规范化为空字符串，两个 UTC 时刻的先后关系不在此处验证。
+    /// </summary>
     public EmTrajectoryMetadata(
         string trajectoryId,
         DateTimeOffset generatedAtUtc,
@@ -52,16 +58,63 @@ public sealed class EmTrajectoryMetadata
         PlanningScope = planningScope;
     }
 
+    /// <summary>
+    /// 非空白的本次发布轨迹标识，由消费者用于去重、替换和追踪。
+    /// </summary>
     public string TrajectoryId { get; }
+
+    /// <summary>
+    /// 生成此元数据的 UTC 时刻；值原样保存，构造器不与生效时刻比较。
+    /// </summary>
     public DateTimeOffset GeneratedAtUtc { get; }
+
+    /// <summary>
+    /// 轨迹计划开始生效的 UTC 时刻；执行消费者负责按其调度策略解释。
+    /// </summary>
     public DateTimeOffset EffectiveAtUtc { get; }
+
+    /// <summary>
+    /// 地图快照的非负版本标识；用于确认轨迹依赖的环境版本。
+    /// </summary>
     public long MapSnapshotId { get; }
+
+    /// <summary>
+    /// 非空白的输入参考路径标识；用于关联轨迹的几何来源。
+    /// </summary>
     public string ReferencePathId { get; }
+
+    /// <summary>
+    /// 车辆状态的非负序列版本；用于判断轨迹是否基于当前状态快照。
+    /// </summary>
     public long VehicleStateSequenceId { get; }
+
+    /// <summary>
+    /// 前一轨迹的可选标识；null 输入已规范化为空字符串，空字符串表示没有可关联的前轨迹标识。
+    /// </summary>
     public string PreviousTrajectoryId { get; }
+
+    /// <summary>
+    /// 参考路径中此轨迹所属的非负方向段索引。
+    /// </summary>
     public int SegmentIndex { get; }
+
+    /// <summary>
+    /// 所属方向段的已验证行驶方向。
+    /// </summary>
     public TravelDirection Direction { get; }
+
+    /// <summary>
+    /// 轨迹最后一个终端的已验证业务类型。
+    /// </summary>
     public EmTerminalType TerminalType { get; }
+
+    /// <summary>
+    /// 生成轨迹时采用的已验证纵向终端速度语义。
+    /// </summary>
     public EmLongitudinalMode LongitudinalMode { get; }
+
+    /// <summary>
+    /// 生成轨迹时采用的已验证规划覆盖范围。
+    /// </summary>
     public EmPlanningScope PlanningScope { get; }
 }