chore: save current workspace progress

ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs

@@ -12,7 +12,7 @@ using MultiWheelC.TrajectoryPlanning.Utils;
 
 namespace MultiWheelC.TrajectoryPlanning.PathSmoothing.LocalG2;
 
-/// <summary>对一个局部 G2 替换候选执行区域质量门和完整路径安全复核。</summary>
+/// <summary>对局部 G2 替换候选执行区域质量门、整条路径几何重算及碰撞安全复核。</summary>
 internal sealed class LocalG2CandidateEvaluator
 {
     private const double CurvatureRangeTolerance = 1e-6d;
@@ -25,11 +25,16 @@ internal sealed class LocalG2CandidateEvaluator
     private readonly LocalG2PathSplicer _splicer;
     private readonly SmoothedPathValidator _validator;
 
+    /// <summary>使用默认几何分析、路径拼接和安全校验器创建候选评估器。</summary>
     internal LocalG2CandidateEvaluator()
         : this(new PathGeometryAnalyzer(), new LocalG2PathSplicer(), new SmoothedPathValidator())
     {
     }
 
+    /// <summary>使用注入的依赖创建候选评估器，便于复用统一的几何与碰撞判定规则。</summary>
+    /// <param name="analyzer">将预处理路径转换为带曲率指标的 <see cref="PathGeometryAnalysis"/> 的分析器。</param>
+    /// <param name="splicer">将候选窗口替换回当前路径并维持换向拓扑的拼接器。</param>
+    /// <param name="validator">对完整候选路径执行碰撞、净空和轨迹不变量检查的校验器。</param>
     internal LocalG2CandidateEvaluator(
         PathGeometryAnalyzer analyzer,
         LocalG2PathSplicer splicer,
@@ -40,6 +45,15 @@ internal sealed class LocalG2CandidateEvaluator
         _validator = validator ?? throw new ArgumentNullException(nameof(validator));
     }
 
+    /// <summary>评估一个局部 G2 候选，仅在全部质量门与完整路径安全复核通过时接受。</summary>
+    /// <param name="rawPath">未经局部替换的基线路径；用于约束曲率范围和总长度变化。</param>
+    /// <param name="currentPath">已接受先前窗口替换的当前路径；本候选将在其指定方向段内拼接。</param>
+    /// <param name="region">候选所属的单一行驶方向平滑区域。</param>
+    /// <param name="candidate">待评估候选的窗口边界与几何点；坐标和弧长单位为 m。</param>
+    /// <param name="request">平滑请求，提供地图、车辆模型、采样间距 m 和安全阈值。</param>
+    /// <param name="options">局部 G2 质量门选项，包括偏差 m、曲率导数 1/m² 和代价回退阈值。</param>
+    /// <param name="cancellationToken">取消令牌；取消时抛出 <see cref="OperationCanceledException"/>。</param>
+    /// <returns>包含接受状态、失败原因和度量值的 <see cref="LocalG2CandidateEvaluation"/>；拒绝时不发布候选路径。</returns>
     internal LocalG2CandidateEvaluation Evaluate(
         PreparedPath rawPath,
         PreparedPath currentPath,
@@ -67,7 +81,9 @@ internal sealed class LocalG2CandidateEvaluator
                 string.IsNullOrEmpty(reason) ? "局部 G2 区域几何分析失败。" : reason);
         }
 
-        if (!VehicleKinematics.TryGetMaximumCurvaturePerMeter(request.Vehicle, out double vehicleMaximumCurvature))
+        if (!CurvatureLimitPolicy.TryGetAllowedMaximumVehicleCurvaturePerMeter(
+                request.Vehicle, request.Configuration.CurvatureLimitRadiusToleranceMeters,
+                out double vehicleMaximumCurvature))
             return Rejected(candidateIndex, PathSmoothingRegionFailureReason.CandidateGenerationFailed, "车辆曲率约束无效。");
         if (candidateAnalysis.MaximumAbsoluteVehicleCurvaturePerMeter > vehicleMaximumCurvature + CurvatureRangeTolerance)
             return Rejected(candidateIndex, PathSmoothingRegionFailureReason.CurvatureExceeded, "局部 G2 候选超过车辆曲率上限。");
@@ -91,7 +107,9 @@ internal sealed class LocalG2CandidateEvaluator
         }
 
         if (!_validator.TryValidate(fullAnalysis.Path, fullAnalysis.Segments, rawPath, request.Map, request.Vehicle,
-                request.Configuration.MaximumCollisionCheckStepMeters, out IReadOnlyList<SmoothedPathPoint> safePath,
+                request.Configuration.MaximumCollisionCheckStepMeters,
+                request.Configuration.CurvatureLimitRadiusToleranceMeters,
+                out IReadOnlyList<SmoothedPathPoint> safePath,
                 out double minimumClearance, out reason))
         {
             return Rejected(candidateIndex, PathSmoothingRegionFailureReason.Collision,
@@ -145,6 +163,9 @@ internal sealed class LocalG2CandidateEvaluator
             "Accepted");
     }
 
+    /// <summary>在已通过质量门的候选中按偏差、峰值曲率导数、变化代价、长度变化和索引稳定选优。</summary>
+    /// <param name="evaluations">待比较的候选评估结果集合；仅 <c>Accepted</c> 为 <see langword="true"/> 的项可入选。</param>
+    /// <returns>最优的已接受评估；若没有合格项，返回带失败原因的拒绝评估。</returns>
     internal static LocalG2CandidateEvaluation SelectBest(IReadOnlyList<LocalG2CandidateEvaluation> evaluations)
     {
         if (evaluations == null) throw new ArgumentNullException(nameof(evaluations));