docs: explain full-direction EM observation

ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md

@@ -1,6 +1,6 @@
 # EM Planner 轨迹规划
 
-`EMPlanner` 位于空间路径之后，针对一个已验证的前进或倒车方向段生成带时间、速度、曲率和终端语义的不可变 `EmTrajectory`。它执行静态走廊构建、LS 横向优化、ST 纵向优化、轨迹装配和独立世界空间复核；不读取 UI、定位、轮速、硬件、系统时钟或当前工作目录。
+`EMPlanner` 位于空间路径之后，针对一个已验证的前进或倒车方向段生成带时间、速度、曲率和终端语义的不可变 `EmTrajectory`。它执行静态走廊构建、LS 横向优化、ST 纵向优化、轨迹装配和独立世界空间复核，并显式支持 `FullDirectionSegment` 与 `RollingHorizon` 两种规划范围；不读取 UI、定位、轮速、硬件、系统时钟或当前工作目录。
 
 ```text
 PlanningGridMap -> Hybrid A* CoarsePath -> Local G2 PathSmoothing
@@ -32,7 +32,7 @@ EMPlanner/
 ├── README.md
 ├── Configuration/
 │   ├── EmPlannerConfiguration.cs                 # 不可变快照前的配置根与默认值
-│   ├── SchedulingConfiguration.cs                # 0.20 s 重规划、6 s / 5 m 视界和输出时间步长
+│   ├── SchedulingConfiguration.cs                # 0.20 s 重规划、滚动视窗、自适应 knot/发布上限和输出时间步长
 │   ├── CorridorConfiguration.cs                  # 走廊采样、偏移和净空
 │   ├── FrenetConfiguration.cs                    # 投影距离、分母和边界锚点容差
 │   ├── LateralConfiguration.cs / LateralWeights.cs
@@ -94,6 +94,9 @@ LS 的变量是 `l`、`dl`、`ddl` 和区间 `dddl`；它对静态走廊、导
 | 静态走廊、LS、ST 或停车条件不可行 | `CorridorInfeasible`、`LateralInfeasible`、`LongitudinalInfeasible`、`StoppingDistanceInsufficient` | 空 | 不发布；由上层决定重试、停车或重新选路 |
 | 求解器不可用、超时、取消或发布复核失败 | `SolverUnavailable`、`SolverTimedOut`、`Cancelled`、`ValidationFailed`、`Failed` | 空 | 读取 `FailureReason`；不得使用中间轨迹 |
 | 已被更新周期替代 | `Superseded` | 空 | 由滚动协调器忽略旧结果 |
+| 完整方向段无有效进度 | `NoProgress` | 空 | 不发布；仅真实终点容差内或受监督停车保持观察可合法零进度 |
+| 完整方向段终端位姿超差 | `TerminalPoseMismatch` | 空 | 不发布；位置误差超过 `0.03 m` 或归一化 yaw 误差超过 `5°` |
+| 自适应 knots 或发布样本超限 | `FullSegmentResourceLimitExceeded` | 空 | 不发布；不得截断轨迹或回退滚动模式 |
 
 `FailureReason` 始终以 `map=...;reference=...;state=...;previous=...;segment=...` 开头，供调用方追踪地图、参考路径、状态、上一轨迹和方向段绑定。
 
@@ -144,7 +147,8 @@ var request = new EmPlanningRequest(
     segmentIndex: 0, previousTrajectory: null,
     requestedAtUtc: capturedAt, effectiveAtUtc: capturedAt,
     outputTrajectoryId: "trajectory-42", referencePathId: "path-17", previousTrajectoryId: "",
-    motionModel: EmMotionModel.NonholonomicForwardReverse);
+    motionModel: EmMotionModel.NonholonomicForwardReverse,
+    planningScope: EmPlanningScope.FullDirectionSegment);
 
 EmPlanningResult result = service.Plan(request, CancellationToken.None);
 if (result.Status != EmPlanningStatus.Success && result.Status != EmPlanningStatus.SuccessWithFallback)
@@ -153,13 +157,21 @@ if (result.Status != EmPlanningStatus.Success && result.Status != EmPlanningStat
 EmTrajectory trajectory = result.Trajectory;
 ```
 
-## Rolling longitudinal planning semantics
+## 规划范围：FullDirectionSegment 与 RollingHorizon
 
-`DistanceHorizonMeters` controls the L-S reference window. `TimeHorizonSeconds` controls the S-T output duration.
-Only a real `Goal` or `GearSwitchApproach` boundary may require an exact zero-speed terminal. `RollingContinuation`
-and `ApproachStopBoundary` may publish nonzero terminal speed; they do not add a synthetic zero-speed hold tail.
-`ExactStopAtBoundary` instead includes a real boundary anchor and a stationary S/U/A stabilization interval inside the
-QP horizon. `ZeroSpeedHoldSeconds`, when configured, is appended only after that QP horizon.
+`EmPlanningRequest.PlanningScope` 显式选择一次 `Plan` 的边界语义；MovementTest 默认使用 `FullDirectionSegment`。
+
+### FullDirectionSegment
+
+- 对完整活动方向段做一次优化；`s_end` 来自已选 Local G2 的实际 `PathS`，`T_end` 由可行加速度、巡航、jerk 限速停止和零速 hold 推导，不依赖旧的距离/时间截断窗口。
+- 前进期望/硬上限为 `1.0 m/s`，倒车期望/硬上限为 `0.5 m/s`。
+- 成功终端必须停止，世界位置误差不超过 `0.03 m`，归一化 yaw 误差不超过 `5°`（约 `0.0873 rad`）。
+- `NoProgress`、`TerminalPoseMismatch`、`FullSegmentResourceLimitExceeded` 失败均返回空轨迹，不降级为滚动或截断发布。
+- `DistanceHorizonMeters` 与 `TimeHorizonSeconds` 作为兼容字段保留，但不用于截断 full 模式。
+
+### RollingHorizon
+
+`DistanceHorizonMeters` 控制 L-S 参考窗口，`TimeHorizonSeconds` 控制 S-T 输出时长。只有真实 `Goal` 或换向边界要求 `ExactStopAtBoundary` 零速终端；`RollingContinuation` 与 `ApproachStopBoundary` 可发布非零末端速度，不追加合成零速 hold tail。`ExactStopAtBoundary` 包含真实边界锚点和 QP 视界内的静止稳定区间，`ZeroSpeedHoldSeconds` 只在 QP 视界之后追加。
 
 该服务不负责周期调用、版本淘汰、轨迹采样或控制命令。需要滚动运行时，将成功结果交给 [TrajectoryExecution](../TrajectoryExecution/README.md)，并由调用方管理状态捕获和周期。
 
@@ -167,13 +179,13 @@ QP horizon. `ZeroSpeedHoldSeconds`, when configured, is appended only after that
 
 ### 第 1 步：冻结一致的请求快照
 
-`EmPlanningRequest` 必须包含同一版本的 `PathSmoothingResult` 和 `PlanningGridMap`、当前 `VehicleParameters`、不可变 `VehicleMotionState`、完整 `EmPlannerConfiguration`、方向段索引、时间、ID 和运动模型。不要在 `Plan` 进行期间修改这些对象或从 UI/硬件重新读取值。
+`EmPlanningRequest` 必须包含同一版本的 `PathSmoothingResult` 和 `PlanningGridMap`、当前 `VehicleParameters`、不可变 `VehicleMotionState`、完整 `EmPlannerConfiguration`、方向段索引、时间、ID、运动模型和 `PlanningScope`。不要在 `Plan` 进行期间修改这些对象或从 UI/硬件重新读取值。
 
 车辆状态中的速度带有符号：正数表示前进，负数表示倒车；速度接近配置的停车容差时按停车处理。`SequenceId`、地图快照 ID、参考路径 ID 和上一轨迹 ID 是诊断及滚动执行身份的一部分。
 
 ### 第 2 步：选择方向段与规划终端
 
-一次请求只选择一个平滑路径方向段。服务从状态投影处开始，按配置的 `6.0 s` / `5.0 m` 视界选择精确终端：未到方向段边界时为 `RollingSafetyStop`，到换向边界前为 `GearSwitch`，最终段终点为 `Goal`。成功轨迹在终端精确停车，并以 `0.05 s` 间隔提供 `0.20 s` 同姿态、零速度 hold tail。
+一次请求只选择一个平滑路径方向段，并显式传入 `EmPlanningScope`。`FullDirectionSegment` 从状态投影处规划到该方向段真实终点（`GearSwitch` 或 `Goal`），`s_end` 取自 Local G2 实际 `PathS`，`T_end` 由可行加速度/巡航/停止包络推导，不再以 `TimeHorizonSeconds` 或 `DistanceHorizonMeters` 截断。`RollingHorizon` 才使用 legacy 视界选择 `RollingSafetyStop`、`GearSwitch` 或 `Goal`；精确停车边界成功后提供同姿态、零速度 hold tail。
 
 上一条轨迹仅能作为同方向、同方向段、位于当前视界内的 Frenet 种子。种子用于保持横向连续性，不能让规划跨过换向边界或绕过静态走廊连通性检查。