diff --git a/docs/superpowers/handoffs/em-full-direction-visualization/phase-04.md b/docs/superpowers/handoffs/em-full-direction-visualization/phase-04.md new file mode 100644 index 0000000..4dc862b --- /dev/null +++ b/docs/superpowers/handoffs/em-full-direction-visualization/phase-04.md @@ -0,0 +1,102 @@ +# 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: + +```text +full direction segment is planned only once per active segment expected 1 but was 4. +``` + +即当前完整方向段仍按协调器节拍重复开始计划。 + +GREEN: + +```powershell +dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation +``` + +退出码 0,输出 `PASS trajectory-observation`。 + +执行器源审计: + +```powershell +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`,上一交接文件为本文件;调用方需在最终答复中提供本交接提交的真实哈希并验证可达。