ParkingRobot/docs/superpowers/handoffs/em-full-direction-visualization/phase-04.md

EM 完整方向段可视化修复 — Phase 04 交接

状态

完成，2026-08-07。

启动分支为 trajplanner，启动 HEAD 为 57d8abb（Phase 03 handoff）。已确认 3269d55、162f1a2、0bba8d7、e844fe0、57d8abb 均为本阶段提交的祖先。

本阶段实现提交：

• ab3204b — feat: observe one full EM direction segment

本交接文件单独提交；其真实提交哈希由提交后的最终答复提供给 Phase 05。

目标与非目标

完成主计划 Task 6：MovementTest 每个活动方向段最多一次完整规划，换向确认后才允许下一段的新计划。

未进入 Task 7+、Web、Native Painter、跨段规划扩展或实车操作。MovementTest 保持 OBSERVE_ONLY，未新增任何底盘、转向、制动、电机或换挡写输出。

实现摘要

• TrajectoryObservationSettings.PlanningScope 默认 EmPlanningScope.FullDirectionSegment，经过 CreateValidatedSnapshot 复制并验证。
• 批准的观察默认值：Web 默认启用、Native Painter 默认关闭、OutputTimeStepSeconds 保持 0.1 s；TimeHorizonSeconds 仅作为滚动兼容字段标注。
• TrajectoryObservationController 保存经过验证的设置快照，并把 PlanningScope 传播到每个 EmPlanningRequest。
• 控制器新增 plannedSegmentIndex 与 planAttemptedForActiveSegment：完整模式下 ShouldStartCycle 只允许每个活动方向段一次；StartCycle 在启动异步计划前置位；只有 TryAdvanceSegment 确认 N 到 N+1 后才复位。
• 完整段规划失败保持可见且不自动滚动重试。
• 保留已有停车保持、三个正确带符号速度样本、显式等待文案和 active segment 高亮。
• 静态快照配置组新增 PlanningScope。

修改文件

• ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationContracts.cs
• ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPipeline.cs
• ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs
• ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs
• ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSettingsChecks.cs
• ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs

TrajectoryObservationSegmentChecks.cs 保持白名单内但本阶段无改动。

新增或改变的接口

• TrajectoryObservationSettings.PlanningScope，默认 FullDirectionSegment，快照复制并在 Validate 中拒绝未定义枚举值。
• TrajectoryObservationMovementTest.UseFullDirectionSegmentPlanning，默认 true，映射为 settings 的 PlanningScope。
• TrajectoryObservationController.ShouldStartCycle：完整模式不再委托协调器节拍。
• TrajectoryObservationController.StartCycle：使用已验证 scope，并在启动异步任务前设置 one-shot 标志。
• TrajectoryObservationController.TryAdvanceSegment：确认换向后复位 one-shot 标志。

RED / GREEN / 回归证据

首次 RED 被既有用户脏配置 EmPlannerConfiguration.cs 的 DistanceHorizonMeters = 500d 拦住：原测试硬编码 distanceHorizon=5.00m。未修改该脏文件；改为从 CreateEffectiveConfigurationSnapshot 动态读取实际距离视界后断言。

随后确认 Task 6 有效 RED：

full direction segment is planned only once per active segment expected 1 but was 4.

即当前完整方向段仍按协调器节拍重复开始计划。

GREEN：

dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation

退出码 0，输出 PASS trajectory-observation。

执行器源审计：

rg -n "SendXYThSpeed|SendMotion|DriveStop|PredefinedDriveStop|AccumulateSpeed|SetGear|SetBrake" ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest

无匹配。

git diff --check 退出码 0；输出仅有既有 LF/CRLF 提示，无空白错误。

工作区保护

保留并未回退用户既有脏工作区，包括但不限于 EmPlannerConfiguration.cs、MovementTest.TrajectoryObservationTest.cs 中用户原有的 TimeHorizonSeconds = 20d、EnableWebVisualization = true、EnableNativePainterVisualization = true，以及 PathSmoothing、CoarsePath、Map、文档和未跟踪报告等改动。

本阶段只修改白名单实现/测试文件；未使用 git reset --hard、git checkout --、git clean、git add . 或 git add -A。

已知警告与偏差

• 既有两条编译 warning 保留：Lidar2dDetect2LegTray.LegWidth 与 MultiWheelChassis.GetSteerWheels()。
• 既有诊断测试因用户脏配置从硬编码 5.00m 改为读取实际生效配置；未改写用户脏文件。
• MovementTest 入口的 Native Painter 保持用户脏配置 true；TrajectoryObservationSettings 类的批准默认值仍为 false。

未运行项

• 未进入 Phase 05 或后续任何阶段。
• 未执行 Web、Painter、跨段扩展或实车操作。
• 未运行 em-core-all；本阶段验证命令按任务要求仅执行 trajectory-observation、执行器审计和 git diff --check。

Phase 05 事实

对应主计划 Task 7，阶段执行计划 Task 5：统一快照、路径图层、曲线单位、s_end、车辆与换向语义。

Phase 05 的 Phase 04 实现提交为 ab3204b，上一交接文件为本文件；调用方需在最终答复中提供本交接提交的真实哈希并验证可达。