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

ClumsyPilot/ParkrobTrajplanner/EMPlanner/Contracts/EmPlanningResult.cs

@@ -2,8 +2,14 @@ using System;
 
 namespace MultiWheelC.TrajectoryPlanning.EMPlanner;
 
+/// <summary>
+/// 一次 EM 规划的不可变结果。只有成功状态才携带可发布的完整轨迹；其余状态仅提供诊断，不能作为部分执行轨迹消费。
+/// </summary>
 public sealed class EmPlanningResult
 {
+    /// <summary>
+    /// 创建规划结果并强制成功状态与轨迹发布的一致性：<see cref="EmPlanningStatus.Success"/> 和 <see cref="EmPlanningStatus.SuccessWithFallback"/> 必须提供非 null 轨迹，其他状态必须提供 null 轨迹；null 失败原因规范化为空字符串。
+    /// </summary>
     public EmPlanningResult(EmPlanningStatus status, EmTrajectory trajectory, string failureReason)
     {
         if (!Enum.IsDefined(typeof(EmPlanningStatus), status))
@@ -20,9 +26,18 @@ public sealed class EmPlanningResult
         FailureReason = failureReason ?? string.Empty;
     }
 
+    /// <summary>
+    /// 本次规划的最终状态；消费者必须先判断其是否为成功状态，再访问可发布轨迹。
+    /// </summary>
     public EmPlanningStatus Status { get; }
 
+    /// <summary>
+    /// 仅在成功或成功降级状态下存在的完整可发布轨迹；失败、取消和无效输入结果始终为 null，消费者不得把失败结果当作部分轨迹执行。
+    /// </summary>
     public EmTrajectory Trajectory { get; }
 
+    /// <summary>
+    /// 面向诊断的失败或降级原因；null 输入已规范化为空字符串，不替代 <see cref="Status"/> 的机器可读状态。
+    /// </summary>
     public string FailureReason { get; }
 }