From fda84ce148bc43eeac87cde9a0fae39d20080db9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=A2=81=E8=96=84=E4=BA=91?= <lby115@126.com>
Date: Tue, 4 Aug 2026 14:17:56 +0800
Subject: [PATCH] docs: document smoothing value contracts

---
 .../Contracts/LocalG2QuinticOptions.cs        | 11 +++++++-
 .../Contracts/PathQualityMetrics.cs           | 27 ++++++++++++++++--
 .../PathSmoothingRegionFailureReason.cs       | 13 ++++++++-
 .../Contracts/PathSmoothingRegionReport.cs    | 20 +++++++++++++
 .../Contracts/PathSmoothingRegionStatus.cs    |  4 ++-
 .../Contracts/SmoothedPathPoint.cs            | 28 ++++++++++++++++++-
 .../Contracts/SmoothedPathSegment.cs          |  7 +++++
 7 files changed, 104 insertions(+), 6 deletions(-)

diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs
index 7bc1e64..a6b88af 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs
@@ -1,15 +1,24 @@
 namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;
 
-/// <summary>局部 G2 五次过渡的可配置阈值。</summary>
+/// <summary>局部 G2 五次过渡窗口、候选数量和改进阈值的可配置快照；长度单位为 m，曲率跳变单位为 1/m。</summary>
 public sealed class LocalG2QuinticOptions
 {
+    /// <summary>允许候选窗口的最小弧长，单位 m。</summary>
     public double MinimumWindowLengthMeters { get; set; } = 0.20d;
+    /// <summary>优先尝试的窗口弧长，单位 m。</summary>
     public double PreferredWindowLengthMeters { get; set; } = 0.50d;
+    /// <summary>允许候选窗口的最大弧长，单位 m。</summary>
     public double MaximumWindowLengthMeters { get; set; } = 0.80d;
+    /// <summary>候选相对原始路径允许的最大几何偏移，单位 m。</summary>
     public double MaximumDeviationMeters { get; set; } = 0.10d;
+    /// <summary>识别曲率跳变的绝对下限，单位 1/m。</summary>
     public double AbsoluteCurvatureJumpFloorPerMeter { get; set; } = 0.001d;
+    /// <summary>曲率跳变相对车辆最大允许曲率的比例阈值。</summary>
     public double CurvatureJumpRatioOfMaximum { get; set; } = 0.05d;
+    /// <summary>接受候选所需的峰值曲率导数最小改善比例。</summary>
     public double MinimumPeakGradientImprovementRatio { get; set; } = 0.20d;
+    /// <summary>候选相对原路径允许的曲率变化代价最大退化比例。</summary>
     public double MaximumVariationCostRegressionRatio { get; set; } = 0.02d;
+    /// <summary>每个局部区域允许评估的候选数量上限。</summary>
     public int MaximumCandidatesPerRegion { get; set; } = 12;
 }
diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs
index 251b387..22b7b09 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs
@@ -9,7 +9,18 @@ public sealed class PathQualityMetrics
     {
     }
 
-    /// <summary>创建完整的质量指标快照。</summary>
+    /// <summary>创建不显式提供曲率导数峰值的完整质量指标快照；曲率导数峰值按 0 处理。</summary>
+    /// <param name="isFeasible">是否通过完整安全和运动学复核。</param>
+    /// <param name="pathLengthMeters">路径总弧长，单位 m。</param>
+    /// <param name="maximumAbsoluteVehicleCurvaturePerMeter">绝对车辆曲率峰值，单位 1/m。</param>
+    /// <param name="rootMeanSquareVehicleCurvaturePerMeter">车辆曲率均方根，单位 1/m。</param>
+    /// <param name="totalAbsoluteCurvatureVariationPerMeter">按方向段累计的绝对曲率变化，单位 1/m。</param>
+    /// <param name="curvatureVariationEnergy">无单位的曲率变化能量/代价。</param>
+    /// <param name="minimumBodyClearanceMeters">扩大车体的最小保守净空，单位 m。</param>
+    /// <param name="lengthChangePercent">相对原始粗路径的长度变化百分比。</param>
+    /// <param name="peakCurvatureChangePercent">相对原始粗路径的峰值曲率变化百分比。</param>
+    /// <param name="curvatureVariationChangePercent">相对原始粗路径的曲率变化百分比。</param>
+    /// <param name="minimumClearanceChangeMeters">相对原始粗路径的最小净空变化，单位 m。</param>
     public PathQualityMetrics(
         bool isFeasible,
         double pathLengthMeters,
@@ -38,7 +49,19 @@ public sealed class PathQualityMetrics
     {
     }
 
-    /// <summary>创建带有曲率导数峰值的完整质量指标快照。</summary>
+    /// <summary>创建包含曲率导数峰值的完整质量指标快照。</summary>
+    /// <param name="isFeasible">是否通过完整安全和运动学复核。</param>
+    /// <param name="pathLengthMeters">路径总弧长，单位 m。</param>
+    /// <param name="maximumAbsoluteVehicleCurvaturePerMeter">绝对车辆曲率峰值，单位 1/m。</param>
+    /// <param name="maximumAbsoluteVehicleCurvatureDerivativePerSquareMeter">绝对车辆曲率导数峰值，单位 1/m²。</param>
+    /// <param name="rootMeanSquareVehicleCurvaturePerMeter">车辆曲率均方根，单位 1/m。</param>
+    /// <param name="totalAbsoluteCurvatureVariationPerMeter">按方向段累计的绝对曲率变化，单位 1/m。</param>
+    /// <param name="curvatureVariationEnergy">无单位的曲率变化能量/代价。</param>
+    /// <param name="minimumBodyClearanceMeters">扩大车体的最小保守净空，单位 m。</param>
+    /// <param name="lengthChangePercent">相对原始粗路径的长度变化百分比。</param>
+    /// <param name="peakCurvatureChangePercent">相对原始粗路径的峰值曲率变化百分比。</param>
+    /// <param name="curvatureVariationChangePercent">相对原始粗路径的曲率变化百分比。</param>
+    /// <param name="minimumClearanceChangeMeters">相对原始粗路径的最小净空变化，单位 m。</param>
     public PathQualityMetrics(
         bool isFeasible,
         double pathLengthMeters,
diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs
index 91b5bf2..f763cb0 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs
@@ -1,17 +1,28 @@
 namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;
 
-/// <summary>局部 G2 区域未替换原始路径的稳定原因。</summary>
+/// <summary>局部 G2 区域未替换原始路径的稳定原因；该枚举解释保留原始几何，而非发布未验证候选。</summary>
 public enum PathSmoothingRegionFailureReason
 {
+    /// <summary>区域已改进或无需拒绝原因。</summary>
     None,
+    /// <summary>无法在同一方向段内构造满足长度约束的窗口。</summary>
     WindowUnavailable,
+    /// <summary>候选曲线无法生成或不满足基本几何条件。</summary>
     CandidateGenerationFailed,
+    /// <summary>候选车体或扫掠与地图障碍发生碰撞。</summary>
     Collision,
+    /// <summary>候选未达到所需最小净空，单位要求见配置。</summary>
     InsufficientClearance,
+    /// <summary>候选车辆曲率超过最大允许值，单位 1/m。</summary>
     CurvatureExceeded,
+    /// <summary>候选在连续采样或拼接处出现曲率超限。</summary>
     CurvatureOvershoot,
+    /// <summary>候选相对原始路径的偏移超过最大限制，单位 m。</summary>
     DeviationExceeded,
+    /// <summary>候选未满足峰值梯度改善阈值。</summary>
     InsufficientImprovement,
+    /// <summary>候选曲率变化代价相对原始路径退化超过允许比例。</summary>
     VariationCostRegression,
+    /// <summary>局部候选通过但整条路径独立复核失败，已回滚到原始几何。</summary>
     GlobalValidationRollback,
 }
diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs
index 4004314..bee5b37 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs
@@ -6,6 +6,26 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;
 /// <summary>单个局部 G2 平滑区域的不可变发布报告。</summary>
 public sealed class PathSmoothingRegionReport
 {
+    /// <summary>创建单个局部 G2 区域的不可变处理报告。</summary>
+    /// <param name="segmentIndex">所属方向段的从零开始索引。</param>
+    /// <param name="startArcLengthMeters">区域在完整路径上的起始弧长，单位 m。</param>
+    /// <param name="endArcLengthMeters">区域在完整路径上的结束弧长，单位 m。</param>
+    /// <param name="curvatureJumpsPerMeter">触发该区域的曲率跳变只读副本，单位 1/m。</param>
+    /// <param name="plannedWindowLengthMeters">规划窗口长度，单位 m。</param>
+    /// <param name="actualWindowLengthMeters">实际参与平滑的窗口长度，单位 m。</param>
+    /// <param name="leftWindowLengthMeters">锚点左侧窗口长度，单位 m。</param>
+    /// <param name="rightWindowLengthMeters">锚点右侧窗口长度，单位 m。</param>
+    /// <param name="candidateCount">已评估候选数量。</param>
+    /// <param name="selectedCandidateIndex">改进时选中候选索引；未改进时结果固定为 -1。</param>
+    /// <param name="status">区域是替换为改进候选还是保留原始几何。</param>
+    /// <param name="failureReason">未替换原始几何时的稳定拒绝原因。</param>
+    /// <param name="rawPeakCurvatureDerivativePerSquareMeter">原始峰值曲率导数，单位 1/m²。</param>
+    /// <param name="resultPeakCurvatureDerivativePerSquareMeter">结果峰值曲率导数，单位 1/m²。</param>
+    /// <param name="rawCurvatureVariationCost">原始曲率变化代价。</param>
+    /// <param name="resultCurvatureVariationCost">结果曲率变化代价。</param>
+    /// <param name="maximumDeviationMeters">候选相对原始路径最大偏移，单位 m。</param>
+    /// <param name="minimumBodyClearanceMeters">扩大车体最小保守净空，单位 m。</param>
+    /// <param name="maximumAbsoluteVehicleCurvaturePerMeter">绝对车辆曲率峰值，单位 1/m。</param>
     public PathSmoothingRegionReport(
         int segmentIndex,
         double startArcLengthMeters,
diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs
index 752d3ef..2ec5cbe 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs
@@ -1,8 +1,10 @@
 namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;
 
-/// <summary>单个局部 G2 平滑区域的处理结果。</summary>
+/// <summary>单个局部 G2 平滑区域的处理结果；原始几何被保留时仍是稳定且可发布的选择。</summary>
 public enum PathSmoothingRegionStatus
 {
+    /// <summary>已选择并验证一个改进候选替换区域原始几何。</summary>
     Improved,
+    /// <summary>没有安全且足够改进的候选，保留原始几何。</summary>
     RetainedOriginal,
 }
diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs
index b0a3c8a..532c9d3 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs
@@ -5,6 +5,20 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;
 /// <summary>平滑空间路径上的不可变采样点；位置和长度单位为 m，航向为 rad，曲率为 1/m。</summary>
 public sealed class SmoothedPathPoint
 {
+    /// <summary>
+    /// 创建不显式提供曲率导数的不可变平滑路径点；曲率对弧长导数按 0 处理。
+    /// </summary>
+    /// <param name="xMeters">世界 X 坐标，单位 m。</param>
+    /// <param name="yMeters">世界 Y 坐标，单位 m。</param>
+    /// <param name="headingRadians">规范化车辆航向，单位 rad。</param>
+    /// <param name="unwrappedHeadingRadians">跨越 ±π 后仍连续的车辆航向，单位 rad。</param>
+    /// <param name="arcLengthMeters">从完整路径起点累计的弧长，单位 m。</param>
+    /// <param name="direction">该点所属方向段的实际行驶方向。</param>
+    /// <param name="geometricCurvaturePerMeter">几何曲线曲率，单位 1/m。</param>
+    /// <param name="vehicleCurvaturePerMeter">车辆模型使用的有符号曲率，单位 1/m。</param>
+    /// <param name="bodyClearanceMeters">扩大车体后的保守净空下界，单位 m。</param>
+    /// <param name="isGearSwitchPoint">为 <see langword="true"/> 时表示新方向段开始的精确换向点。</param>
+    /// <param name="source">该点在平滑流程中的来源枚举。</param>
     public SmoothedPathPoint(
         double xMeters,
         double yMeters,
@@ -33,7 +47,19 @@ public sealed class SmoothedPathPoint
     {
     }
 
-    /// <summary>创建带有车辆曲率对弧长导数的不可变采样点。</summary>
+    /// <summary>创建带有车辆曲率对弧长导数的不可变平滑路径点。</summary>
+    /// <param name="xMeters">世界 X 坐标，单位 m。</param>
+    /// <param name="yMeters">世界 Y 坐标，单位 m。</param>
+    /// <param name="headingRadians">规范化车辆航向，单位 rad。</param>
+    /// <param name="unwrappedHeadingRadians">连续展开的车辆航向，单位 rad。</param>
+    /// <param name="arcLengthMeters">从完整路径起点累计的弧长，单位 m。</param>
+    /// <param name="direction">该点所属的前进或倒车方向。</param>
+    /// <param name="geometricCurvaturePerMeter">几何曲率，单位 1/m。</param>
+    /// <param name="vehicleCurvaturePerMeter">车辆曲率，单位 1/m。</param>
+    /// <param name="vehicleCurvatureDerivativePerSquareMeter">车辆曲率对弧长的导数 dκ/ds，单位 1/m²。</param>
+    /// <param name="bodyClearanceMeters">扩大车体后的保守净空下界，单位 m。</param>
+    /// <param name="isGearSwitchPoint">是否为新方向段开始的换向点。</param>
+    /// <param name="source">该点的平滑来源。</param>
     public SmoothedPathPoint(
         double xMeters,
         double yMeters,
diff --git a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs
index 5ce1d95..93c4777 100644
--- a/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs
+++ b/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs
@@ -5,6 +5,13 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;
 /// <summary>平滑路径中方向一致的连续点范围；起止索引均包含在内。</summary>
 public sealed class SmoothedPathSegment
 {
+    /// <summary>创建覆盖平滑路径连续索引范围的方向段。</summary>
+    /// <param name="segmentIndex">从零开始的方向段编号。</param>
+    /// <param name="direction">该段实际行驶方向。</param>
+    /// <param name="startIndex">该段首点在完整平滑路径中的包含式索引。</param>
+    /// <param name="endIndex">该段末点在完整平滑路径中的包含式索引。</param>
+    /// <param name="startsAtGearSwitch">是否从换向后保留的新方向点开始。</param>
+    /// <param name="endsAtGearSwitch">是否在紧邻下一方向段的换向对之前结束。</param>
     public SmoothedPathSegment(
         int segmentIndex,
         TravelDirection direction,