feat: add local G2 smoothing contracts

ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs

@@ -11,18 +11,22 @@ public sealed class PathSmoothingResult
         new ReadOnlyCollection<SmoothedPathPoint>(new List<SmoothedPathPoint>());
     private static readonly IReadOnlyList<SmoothedPathSegment> EmptySegments =
         new ReadOnlyCollection<SmoothedPathSegment>(new List<SmoothedPathSegment>());
+    private static readonly IReadOnlyList<PathSmoothingRegionReport> EmptyRegionReports =
+        new ReadOnlyCollection<PathSmoothingRegionReport>(new List<PathSmoothingRegionReport>());
 
     private PathSmoothingResult(
         PathSmoothingStatus status,
         SmoothingMethod? method,
         IReadOnlyList<SmoothedPathPoint> path,
         IReadOnlyList<SmoothedPathSegment> segments,
-        PathSmoothingDiagnostics diagnostics)
+        PathSmoothingDiagnostics diagnostics,
+        IReadOnlyList<PathSmoothingRegionReport> regionReports)
     {
         Status = status;
         Method = method;
         Path = path;
         Segments = segments;
+        RegionReports = regionReports;
         Diagnostics = diagnostics ?? new PathSmoothingDiagnostics(
             new PathQualityMetrics(),
             TimeSpan.Zero,
@@ -43,6 +47,9 @@ public sealed class PathSmoothingResult
     /// <summary>覆盖 <see cref="Path"/> 的方向分段；其他状态始终为空且不可变。</summary>
     public IReadOnlyList<SmoothedPathSegment> Segments { get; }
 
+    /// <summary>局部 G2 各检测区域的不可变报告；传统算法结果为空。</summary>
+    public IReadOnlyList<PathSmoothingRegionReport> RegionReports { get; }
+
     /// <summary>本次平滑的质量和终止诊断；始终非空。</summary>
     public PathSmoothingDiagnostics Diagnostics { get; }
 
@@ -59,7 +66,8 @@ public sealed class PathSmoothingResult
             method,
             CopyReadOnly(path),
             CopyReadOnly(segments),
-            diagnostics);
+            diagnostics,
+            EmptyRegionReports);
     }
 
     /// <summary>创建经过完整复核的原始粗路径回退结果。</summary>
@@ -75,17 +83,49 @@ public sealed class PathSmoothingResult
             attemptedMethod,
             CopyReadOnly(path),
             CopyReadOnly(segments),
-            diagnostics);
+            diagnostics,
+            EmptyRegionReports);
+    }
+
+    /// <summary>发布经过完整复核的局部 G2 预平滑结果。</summary>
+    public static PathSmoothingResult PublishLocalG2(
+        PathSmoothingStatus status,
+        IReadOnlyList<SmoothedPathPoint> path,
+        IReadOnlyList<SmoothedPathSegment> segments,
+        PathSmoothingDiagnostics diagnostics,
+        IReadOnlyList<PathSmoothingRegionReport> regionReports)
+    {
+        if (status != PathSmoothingStatus.Complete &&
+            status != PathSmoothingStatus.PartialImprovement &&
+            status != PathSmoothingStatus.NotNeeded &&
+            status != PathSmoothingStatus.Unchanged)
+            throw new ArgumentException("Use a Local G2 publication status.", nameof(status));
+        if (regionReports == null)
+            throw new ArgumentNullException(nameof(regionReports));
+
+        ValidatePublishedResult(SmoothingMethod.LocalG2Quintic, path, segments, diagnostics);
+        return new PathSmoothingResult(
+            status,
+            SmoothingMethod.LocalG2Quintic,
+            CopyReadOnly(path),
+            CopyReadOnly(segments),
+            diagnostics,
+            CopyReadOnly(regionReports));
     }
 
     /// <summary>创建不发布路径的失败、不可行、取消或输入无效结果。</summary>
     public static PathSmoothingResult Failure(PathSmoothingStatus status, PathSmoothingDiagnostics diagnostics)
     {
-        if (status == PathSmoothingStatus.Success || status == PathSmoothingStatus.FallbackToCoarsePath)
+        if (status == PathSmoothingStatus.Success ||
+            status == PathSmoothingStatus.FallbackToCoarsePath ||
+            status == PathSmoothingStatus.Complete ||
+            status == PathSmoothingStatus.PartialImprovement ||
+            status == PathSmoothingStatus.NotNeeded ||
+            status == PathSmoothingStatus.Unchanged)
             throw new ArgumentException("Use Success or Fallback to publish a path.", nameof(status));
         if (!Enum.IsDefined(typeof(PathSmoothingStatus), status))
             throw new ArgumentOutOfRangeException(nameof(status));
-        return new PathSmoothingResult(status, null, EmptyPath, EmptySegments, diagnostics);
+        return new PathSmoothingResult(status, null, EmptyPath, EmptySegments, diagnostics, EmptyRegionReports);
     }
 
     private static void ValidatePublishedResult(