# P1 粗路径 Clumsy UI 集成 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 交付可在 Clumsy 中后台运行的七个粗路径测试入口，显示真实规划栅格快照和完整路径信息，并支持传入 AMR 世界位姿与手动目标位姿。

**Architecture:** `CoarsePathScenarioFactory` 保持无 UI 的纯输入构造职责，提供六个可重复的回归场景及一个显式标注为空图演示的“AMR 位姿 + 手动终点”请求创建入口。`MovementTest.CoarsePathTest.cs` 只作为 UI 适配层：把 AMR/目标 mm+deg 转为核心所需的 m+rad，使用一个共享门面在 `Task.Run` 后台运行，并从不可变 `CoarsePathPlanningJobResult` 绘制地图快照和路径。

**Tech Stack:** C# / `netstandard2.0`、现有 Clumsy `MovementTest`/`Painter`、`CoarsePathPlanningService`、PowerShell 反射验证脚本。

## Global Constraints

- `PlanningMapRequest` 的地图、障碍物、AMR 输入和手动目标 X/Y 均为世界 mm；`Pose2D` 和路径 X/Y 为世界 m；核心航向为 rad。
- 项目上游的 AMR `th` 输入按 deg 适配为 `th * Math.PI / 180d`；不得沿用直接将该值传给 `Math.Cos/Sin` 的旧写法。
- AMR 起点必须是车辆几何中心；传感器安装点必须由上游先按外参转换。
- UI 和测试只能调用 `CoarsePathPlanningService.Plan(job, token)`；不得直接实例化 `PlanningMapFactory`、`HybridAStarPlanner`、栅格化器、碰撞器、原语生成器或搜索节点。
- 所有七个 MovementTest 都不得引用 `BasicPilotBase.Chassis`、`SendMotion`、`DriveTask` 或任何底盘控制 API。
- `Test` 不得等待后台任务或读取 `Task.Result`；`TestStop` 先取消令牌，再使运行编号失效、解绑任务并清空 Painter。
- 只在 `PlanningStatus.Success` 绘制路径、方向箭头、换向点和扩大车体检查框；失败、取消和超时只显示地图、起点、终点和状态。
- 代码兼容 `netstandard2.0`，不引入新 NuGet 包；公开类型/成员写中文 XML 文档，复杂单位与并发逻辑写简短中文行注释。
- 不改动 TrapMap 文件或旧 TrapMap 验证脚本；不执行 Git 状态、差异、提交或重置操作。

---

## 文件结构

| 文件 | 变更职责 |
| --- | --- |
| `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/CoarsePathScenarioFactory.cs` | 新建纯场景工厂、六场景枚举、AMR/目标位姿 mm+deg 到核心 `Pose2D` 的转换，以及空图演示手动目标请求。 |
| `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/MovementTest.CoarsePathTest.cs` | 新建七个 UI 入口、共享会话执行器、任务取消、Painter 地图/路径/图例绘制与手动输入解析。 |
| `ClumsyPilot/tests/verify_coarse_path_integration.ps1` | 为工厂行为、单位转换、缓存/换向/无解、UI 源码边界与 README 内容新增真实程序集和文本断言。 |
| `ClumsyPilot/ParkrobTrajplanner/CoarsePath/README.md` | 记录 P1 测试入口、输入单位、空图演示限制、图例、停止语义及无底盘命令边界。 |

### 固定接口

```csharp
namespace MultiWheelC.TrajectoryPlanning.CoarsePath.Test;

public enum CoarsePathTestScenario
{
    ExplicitEmpty,
    RectangleDetour,
    ManualAndTwoLeg,
    CacheHit,
    ReverseGearSwitch,
    NoFeasiblePath,
}

public static class CoarsePathScenarioFactory
{
    public static CoarsePathPlanningJob Create(CoarsePathTestScenario scenario);

    public static CoarsePathPlanningJob CreateManualGoalDemo(
        double startXMillimeters, double startYMillimeters, double startHeadingDegrees,
        double goalXMillimeters, double goalYMillimeters, double goalHeadingDegrees);
}
```

`CreateManualGoalDemo` 只构造带 2,000 mm 边缘留白的显式空图演示请求，并在 README/测试名称中明确其不代表真实环境安全。未来现场入口必须提供真实 `IMapObstacleSource` 快照，而不是修改此方法的语义。

### Task 1: 工厂契约与失败测试

**Files:**

- Modify: `ClumsyPilot/tests/verify_coarse_path_integration.ps1`
- Create later in Task 2: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/CoarsePathScenarioFactory.cs`

**Consumes:** 已有 `CoarsePathPlanningService.Plan(CoarsePathPlanningJob, CancellationToken)`、`Find-Method`、`Assert-True`、`Assert-Equal` 与程序集加载逻辑。

**Produces:** 对 `CoarsePathTestScenario` 和 `CoarsePathScenarioFactory` 的反射行为约束；Task 2 的最小实现必须使这些断言通过。

- [ ] **Step 1: 在集成脚本加入工厂反射测试**

在现有 facade 检查后、最终输出前插入以下 PowerShell。它要求类型和两个公开方法都存在，因此在工厂未创建时失败。

```powershell
$testNamespace = $coarsePath + 'Test.'
$scenarioEnumType = $assembly.GetType($testNamespace + 'CoarsePathTestScenario', $false)
$scenarioFactoryType = $assembly.GetType($testNamespace + 'CoarsePathScenarioFactory', $false)
Assert-True ($scenarioEnumType -ne $null) 'P1 scenario enum must exist.'
Assert-True ($scenarioFactoryType -ne $null) 'P1 scenario factory must exist.'

$factoryCreate = Find-Method $scenarioFactoryType 'Create' @($scenarioEnumType)
$factoryManual = Find-Method $scenarioFactoryType 'CreateManualGoalDemo' @(
    [double], [double], [double], [double], [double], [double])
Assert-True ($factoryCreate -ne $null) 'P1 scenario factory must expose Create(scenario).'
Assert-True ($factoryManual -ne $null) 'P1 scenario factory must expose CreateManualGoalDemo with six doubles.'

$scenarioNames = @('ExplicitEmpty', 'RectangleDetour', 'ManualAndTwoLeg', 'CacheHit', 'ReverseGearSwitch', 'NoFeasiblePath')
foreach ($scenarioName in $scenarioNames) {
    $scenario = [Enum]::Parse($scenarioEnumType, $scenarioName)
    $jobA = $factoryCreate.Invoke($null, @($scenario))
    $jobB = $factoryCreate.Invoke($null, @($scenario))
    Assert-True ($jobA -ne $null) "Scenario $scenarioName must return a job."
    Assert-False ([object]::ReferenceEquals($jobA, $jobB)) "Scenario $scenarioName must return a new job per call."
}

$manualJob = $factoryManual.Invoke($null, @(1000.0, 2000.0, 90.0, 4000.0, 2000.0, 0.0))
Assert-Near 1.0 $manualJob.Start.X 'Manual AMR X must convert mm to m.'
Assert-Near 2.0 $manualJob.Start.Y 'Manual AMR Y must convert mm to m.'
Assert-Near ([Math]::PI / 2.0) $manualJob.Start.Heading 'Manual AMR heading must convert degrees to radians.'
Assert-Near 4.0 $manualJob.Goal.X 'Manual goal X must convert mm to m.'
Assert-Near 0.0 $manualJob.Goal.Heading 'Manual goal heading must convert degrees to radians.'
Assert-True $manualJob.MapRequest.AllowExplicitEmptyMap 'Manual goal demo must declare its empty map explicitly.'
```

- [ ] **Step 2: 运行脚本确认失败**

Run:

```powershell
dotnet build .\ClumsyPilot\ClumsyPilot.csproj --no-restore
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 构建成功；脚本因 `P1 scenario enum must exist.` 失败。

### Task 2: 实现纯场景工厂并通过行为测试

**Files:**

- Create: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/CoarsePathScenarioFactory.cs`
- Test: `ClumsyPilot/tests/verify_coarse_path_integration.ps1`

**Consumes:** Task 1 的枚举和两个公开工厂方法；`MapBoundsMm`、`ManualObstacleSource`、`TwoLegObstacleSource`、`Pose2D`、`VehicleParameters`、`HybridAStarConfiguration`。

**Produces:** 六个可重复 job 与一个空图演示手动 job，供 UI 入口和后续脚本行为断言共同使用。

- [ ] **Step 1: 先建立最小的公共类型和转换辅助函数**

创建工厂文件并定义以下枚举、转换函数和公共入口。所有输入先做有限值检查；非有限输入抛出 `ArgumentOutOfRangeException`，避免伪造核心请求。

```csharp
public enum CoarsePathTestScenario
{
    ExplicitEmpty,
    RectangleDetour,
    ManualAndTwoLeg,
    CacheHit,
    ReverseGearSwitch,
    NoFeasiblePath,
}

public static class CoarsePathScenarioFactory
{
    private const double MillimetersPerMeter = 1000d;
    private const double DegreesToRadians = Math.PI / 180d;
    private const float ResolutionMillimeters = 50f;
    private const double ManualMapPaddingMillimeters = 2000d;

    public static CoarsePathPlanningJob Create(CoarsePathTestScenario scenario)
    {
        switch (scenario)
        {
            case CoarsePathTestScenario.ExplicitEmpty: return CreateExplicitEmpty();
            case CoarsePathTestScenario.RectangleDetour: return CreateRectangleDetour();
            case CoarsePathTestScenario.ManualAndTwoLeg: return CreateManualAndTwoLeg();
            case CoarsePathTestScenario.CacheHit: return CreateRectangleDetour();
            case CoarsePathTestScenario.ReverseGearSwitch: return CreateReverseGearSwitch();
            case CoarsePathTestScenario.NoFeasiblePath: return CreateNoFeasiblePath();
            default: throw new ArgumentOutOfRangeException(nameof(scenario));
        }
    }

    public static CoarsePathPlanningJob CreateManualGoalDemo(
        double startXMillimeters, double startYMillimeters, double startHeadingDegrees,
        double goalXMillimeters, double goalYMillimeters, double goalHeadingDegrees)
    {
        EnsureFinite(startXMillimeters, nameof(startXMillimeters));
        EnsureFinite(startYMillimeters, nameof(startYMillimeters));
        EnsureFinite(startHeadingDegrees, nameof(startHeadingDegrees));
        EnsureFinite(goalXMillimeters, nameof(goalXMillimeters));
        EnsureFinite(goalYMillimeters, nameof(goalYMillimeters));
        EnsureFinite(goalHeadingDegrees, nameof(goalHeadingDegrees));
        return CreateJob(CreateManualDemoMap(startXMillimeters, startYMillimeters, goalXMillimeters, goalYMillimeters),
            ToPose(startXMillimeters, startYMillimeters, startHeadingDegrees),
            ToPose(goalXMillimeters, goalYMillimeters, goalHeadingDegrees), null, GoalDirectionConstraint.Any);
    }

    private static Pose2D ToPose(double xMillimeters, double yMillimeters, double headingDegrees)
        => new Pose2D(xMillimeters / MillimetersPerMeter, yMillimeters / MillimetersPerMeter,
            headingDegrees * DegreesToRadians);
}
```

- [ ] **Step 2: 实现统一请求模板和六个固定场景**

使用统一的车辆和配置，避免场景间无意改变安全或搜索语义。模板必须是新对象：

```csharp
private static CoarsePathPlanningJob CreateJob(PlanningMapRequest mapRequest, Pose2D start, Pose2D goal,
    TravelDirection? startDirection, GoalDirectionConstraint goalDirection)
{
    return new CoarsePathPlanningJob
    {
        MapRequest = mapRequest,
        Start = start,
        Goal = goal,
        Vehicle = new VehicleParameters
        {
            LengthMeters = 0.80d,
            WidthMeters = 0.60d,
            SafetyMarginMeters = 0.05d,
            MaximumCurvaturePerMeter = 1d / 1.20d,
        },
        Configuration = new HybridAStarConfiguration(),
        StartDirection = startDirection,
        GoalDirection = goalDirection,
    };
}
```

固定地图均使用 `new MapBoundsMm(0f, 6000f, 0f, 4000f)`、50 mm 分辨率。以下代码固定各场景的障碍来源和世界位姿，所有 `ManualObstacleSource` 版本为 `1L`、所有必需来源为 `true`：

```csharp
private static CoarsePathPlanningJob CreateExplicitEmpty()
    => CreateJob(CreateMap(true, Array.Empty<IMapObstacleSource>()),
        new Pose2D(1d, 2d, 0d), new Pose2D(5d, 2d, 0d), null, GoalDirectionConstraint.Forward);

private static CoarsePathPlanningJob CreateRectangleDetour()
    => CreateJob(CreateMap(false, new IMapObstacleSource[]
        {
            new ManualObstacleSource("manual", 1L, true, new IMapObstacle[]
                { new AxisAlignedRectangleObstacle(2700f, 3300f, 1200f, 2800f) }),
        }), new Pose2D(1d, 2d, 0d), new Pose2D(5d, 2d, 0d), null, GoalDirectionConstraint.Forward);

private static CoarsePathPlanningJob CreateManualAndTwoLeg()
    => CreateJob(CreateMap(false, new IMapObstacleSource[]
        {
            new ManualObstacleSource("manual", 1L, true, new IMapObstacle[]
            {
                new CircleObstacle(2400f, 1300f, 220f),
                new AxisAlignedRectangleObstacle(3000f, 3600f, 2000f, 2600f),
            }),
            new TwoLegObstacleSource("two-leg", 1L, true,
                new TwoLegProjectionInput(true, 3900f, 2500f, 0d,
                    -180f, -180f, -180f, 180f, 140f, "P1 fixed TwoLeg snapshot.")),
        }), new Pose2D(1d, 1d, 0d), new Pose2D(5d, 3d, 0d), null, GoalDirectionConstraint.Forward);

private static CoarsePathPlanningJob CreateNoFeasiblePath()
    => CreateJob(CreateMap(false, new IMapObstacleSource[]
        {
            new ManualObstacleSource("manual", 1L, true, new IMapObstacle[]
                { new AxisAlignedRectangleObstacle(2900f, 3100f, 0f, 4000f) }),
        }), new Pose2D(1d, 2d, 0d), new Pose2D(5d, 2d, 0d), null, GoalDirectionConstraint.Forward);
```

`CreateMap` 返回新的 `PlanningMapRequest`，固定写入地图边界、分辨率、给定来源和 `AllowExplicitEmptyMap`。倒车换向场景使用空图、起点 `(1,2,0)`、终点 `(4,2,0)`、`StartDirection=Forward`、`GoalDirection=Reverse`，使路径必须以至少一次换向结束。

倒车换向场景使用空图、起点 `(1,2,0)`、终点 `(4,2,0)`、`StartDirection=Forward`、`GoalDirection=Reverse`，使路径必须以至少一次换向结束。若 P0 的离散搜索在此几何下无法稳定得到成功，只允许调整此场景的目标距离或障碍布局，且测试必须继续要求 `IsGearSwitchPoint=true`。

`CreateManualDemoMap` 用起终点 X/Y 的最小/最大值各扩展 `ManualMapPaddingMillimeters`，按 50 mm 向外取整，并明确设置 `AllowExplicitEmptyMap=true` 和空的 `ObstacleSources`。

- [ ] **Step 3: 扩展行为断言以覆盖所有场景的实际状态**

在 Task 1 的反射代码之后增加服务执行测试。它不引用任何 Painter 或 MovementTest：

```powershell
$scenarioService = [Activator]::CreateInstance($serviceType)
foreach ($scenarioName in @('ExplicitEmpty', 'RectangleDetour', 'ManualAndTwoLeg', 'ReverseGearSwitch')) {
    $job = $factoryCreate.Invoke($null, @([Enum]::Parse($scenarioEnumType, $scenarioName)))
    $result = $servicePlan.Invoke($scenarioService, @($job, [Threading.CancellationToken]::None))
    Assert-Equal 'Success' $result.PlanningResult.Status.ToString() "Scenario $scenarioName must succeed."
}

$reverseJob = $factoryCreate.Invoke($null, @([Enum]::Parse($scenarioEnumType, 'ReverseGearSwitch')))
$reverseResult = $servicePlan.Invoke($scenarioService, @($reverseJob, [Threading.CancellationToken]::None))
Assert-True (($reverseResult.PlanningResult.Path | Where-Object { $_.IsGearSwitchPoint }).Count -ge 1) 'Reverse scenario must expose a gear-switch point.'

$noPathJob = $factoryCreate.Invoke($null, @([Enum]::Parse($scenarioEnumType, 'NoFeasiblePath')))
$noPathResult = $servicePlan.Invoke($scenarioService, @($noPathJob, [Threading.CancellationToken]::None))
Assert-Equal 'NoFeasiblePath' $noPathResult.PlanningResult.Status.ToString() 'Barrier scenario must be infeasible.'
Assert-Equal 0 $noPathResult.PlanningResult.Path.Count 'Infeasible scenario must not publish a path.'

$cacheJobA = $factoryCreate.Invoke($null, @([Enum]::Parse($scenarioEnumType, 'CacheHit')))
$cacheJobB = $factoryCreate.Invoke($null, @([Enum]::Parse($scenarioEnumType, 'CacheHit')))
$cacheFirst = $servicePlan.Invoke($scenarioService, @($cacheJobA, [Threading.CancellationToken]::None))
$cacheSecond = $servicePlan.Invoke($scenarioService, @($cacheJobB, [Threading.CancellationToken]::None))
Assert-Equal 'Input' $cacheSecond.MapResult.CacheHit.ToString() 'Cache-hit scenario must reuse the complete map input.'
Assert-Equal $cacheFirst.PlanningResult.Status $cacheSecond.PlanningResult.Status 'Map cache reuse must not change planning status.'
```

- [ ] **Step 4: 运行测试并固定数值场景**

Run:

```powershell
dotnet build .\ClumsyPilot\ClumsyPilot.csproj --no-restore
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 工厂、单位转换、六个固定场景、缓存与无解断言通过；此时尚未加入 MovementTest 源码检查，因此脚本整体通过。

### Task 3: MovementTest 后台会话与完整 Painter 绘制

**Files:**

- Modify: `ClumsyPilot/tests/verify_coarse_path_integration.ps1`
- Create: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/MovementTest.CoarsePathTest.cs`

**Consumes:** Task 2 的 `CoarsePathScenarioFactory.Create` 和 `CreateManualGoalDemo`；`CoarsePathPlanningService`、`CoarsePathPlanningJobResult`、`PlanningGridMap`、`Painter`。

**Produces:** 六个固定场景入口与一个“AMR 位姿 + 手动终点（空图演示）”入口；所有入口通过同一个后台执行器运行和绘制。

- [ ] **Step 1: 写入失败的 UI 源码结构断言**

在 PowerShell 脚本中加入下列纯文本检查，避免在自动化测试中实例化外部 UI：

```powershell
$movementTestPath = Join-Path $plannerRoot 'CoarsePath\Test\MovementTest.CoarsePathTest.cs'
if (-not (Test-Path -LiteralPath $movementTestPath -PathType Leaf)) {
    throw 'P1 coarse-path MovementTest source file must exist.'
}
$movementTestContent = Get-Content -LiteralPath $movementTestPath -Raw
foreach ($required in @(
    '[MovementTest(name = "粗路径-显式空图")]',
    '[MovementTest(name = "粗路径-矩形绕行")]',
    '[MovementTest(name = "粗路径-多来源障碍")]',
    '[MovementTest(name = "粗路径-缓存命中")]',
    '[MovementTest(name = "粗路径-倒车换向")]',
    '[MovementTest(name = "粗路径-无解")]',
    '[MovementTest(name = "粗路径-AMR起点手动终点(空图演示)")]',
    'Task.Run', 'CancellationTokenSource', 'CoarsePathPlanningService',
    'PlanningGridMap', 'IsOccupied', 'ResolutionMm', 'SnapshotId', '图例', 'IsGearSwitchPoint')) {
    Assert-True $movementTestContent.Contains($required) "MovementTest must contain: $required"
}
foreach ($forbidden in @('PlanningMapFactory', 'HybridAStarPlanner', 'MapObstacleRasterizer',
    'FootprintCollisionChecker', 'MotionPrimitiveGenerator', 'HybridAStarSearch',
    'BasicPilotBase.Chassis', 'SendMotion', 'DriveTask', '.Wait()', '.Result')) {
    Assert-False $movementTestContent.Contains($forbidden) "MovementTest must not depend on: $forbidden"
}
```

- [ ] **Step 2: 运行脚本确认 UI 结构检查失败**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 在工厂断言通过后，因 `P1 coarse-path MovementTest source file must exist.` 失败。

- [ ] **Step 3: 实现共享会话执行器与七个薄入口**

在新文件中使用 `namespace MultiWheelC;`，引用 `System.Threading`、`System.Threading.Tasks`、`System.Drawing`、`System.Numerics`、`ClumsyCore`、`MDCSToolBox.Clumsy.Movements` 和 Map/CoarsePath 命名空间。定义一个内部静态执行器，核心形状如下：

```csharp
internal static class CoarsePathMovementTestRunner
{
    private static readonly object SyncRoot = new object();
    private static readonly CoarsePathPlanningService Service = new CoarsePathPlanningService();
    private static readonly Painter Painter = UI.GetPainter("CoarsePathPlanningV1", true);
    private static long _nextRunId;
    private static long _activeRunId;
    private static CancellationTokenSource _activeCancellation;
    private static Task _activeTask;

    internal static void Start(string displayName, CoarsePathPlanningJob job)
    {
        CancellationTokenSource previous;
        long runId;
        var cancellation = new CancellationTokenSource();
        lock (SyncRoot)
        {
            previous = _activeCancellation;
            runId = ++_nextRunId;
            _activeRunId = runId;
            _activeCancellation = cancellation;
            Painter.Clear();
            _activeTask = Task.Run(() => Service.Plan(job, cancellation.Token));
            _activeTask.ContinueWith(task => Complete(runId, displayName, job, cancellation, task),
                CancellationToken.None, TaskContinuationOptions.None, TaskScheduler.Default);
        }
        previous?.Cancel();
    }

    internal static void Stop()
    {
        CancellationTokenSource cancellation;
        lock (SyncRoot)
        {
            cancellation = _activeCancellation;
        }
        cancellation?.Cancel();
        lock (SyncRoot)
        {
            if (!ReferenceEquals(_activeCancellation, cancellation)) return;
            _activeCancellation = null;
            _activeTask = null;
            _activeRunId = ++_nextRunId;
        }
        Painter.Clear();
    }
}
```

`Complete` 必须捕获 `task.Exception`，但正常情况下只接受 `CoarsePathPlanningJobResult`。在锁内确认 `runId == _activeRunId`、任务未取消并且 `task.Status == TaskStatus.RanToCompletion` 后才绘制；无论绘制与否都在 finally 中释放该任务专用 `CancellationTokenSource`。不可在锁内等待任务。

添加一个抽象 `CoarsePathScenarioMovementTest`，其 `Test` 调用 `CoarsePathMovementTestRunner.Start(DisplayName, CoarsePathScenarioFactory.Create(Scenario))`，其 `TestStop` 调用 `Stop()`。实现六个带固定属性名称的密封子类。第七个类在 `Test` 中只读取一次六个 UI 输入：AMR 起点 X/Y/航向和目标 X/Y/航向（分别为 mm/mm/deg），调用 `CreateManualGoalDemo` 后启动；输入解析失败时仅记录错误并不启动任务。

- [ ] **Step 4: 实现确定的地图和结果绘制辅助方法**

在同一执行器内只消费 `job` 与 `CoarsePathPlanningJobResult`，按固定顺序调用以下辅助方法：

```csharp
private static void DrawMap(PlanningGridMap map);
private static void DrawPose(Color color, string label, Pose2D pose);
private static void DrawGoalTolerance(Pose2D goal, HybridAStarConfiguration configuration);
private static void DrawSuccessfulPath(PlanningResult result, VehicleParameters vehicle);
private static void DrawLegendAndStatus(string displayName, CoarsePathPlanningJobResult result, int gridStride);
```

`DrawMap` 画 `[Bounds.XMin, Bounds.XMax) × [Bounds.YMin, Bounds.YMax)` 的粗边界和 X/Y 参考。`gridStride = Max(1, Ceiling(Max(Rows, Cols) / 100d))`；每 `gridStride` 个真实栅格画一条线，状态文字写入 `分辨率=...mm，显示每...格`。遍历 `row/col`，仅对 `map.IsOccupied(row,col)` 为 true 的单元以四条边线画深色格框，确保显示的是最终快照而非原始几何。

`DrawPose` 将 m 转 mm，以圆、朝向短线和标签分别绘制绿色起点、橙色终点。`DrawGoalTolerance` 将位置容差 m 转 mm，绘制橙色容差圆。`DrawSuccessfulPath` 仅在 `result.Status == PlanningStatus.Success` 时运行：相邻路径点按当前点 `Direction` 使用青色（前进）或蓝色（倒车）连线；每隔 10 点画短箭头；`IsGearSwitchPoint` 画紫色圆与“换向”；首、末、换向和每 20 点调用旋转矩形绘制，半长/半宽严格按车辆长宽加安全余量。`DrawLegendAndStatus` 在边界左上方显示边界、占据格、起点、终点、前进、倒车、换向和扩大车体颜色说明，另显示 `SnapshotId`、`MapResult.Status`、`CacheHit`、`PlanningResult.Status`、`Elapsed` 和终止原因。

- [ ] **Step 5: 运行构建与集成脚本**

Run:

```powershell
dotnet build .\ClumsyPilot\ClumsyPilot.csproj --no-restore
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 构建成功；工厂行为、七入口结构、后台取消约束和 Painter 数据来源检查全部通过。

### Task 4: README 与文档断言

**Files:**

- Modify: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/README.md`
- Modify: `ClumsyPilot/tests/verify_coarse_path_integration.ps1`

**Consumes:** Task 2 的 `CreateManualGoalDemo` 单位契约和 Task 3 的七个入口名称、图例颜色和停止行为。

**Produces:** 可独立使用的 P1 UI 说明，以及对其关键安全声明的自动化保护。

- [ ] **Step 1: 为 README 写失败断言**

在现有 README 检查后加入：

```powershell
foreach ($requiredReadmeText in @(
    '## P1：Clumsy 手动测试与可视化',
    '粗路径-AMR起点手动终点(空图演示)',
    'AMR 位姿输入：X/Y 使用世界 mm，th 使用 deg',
    'Pose2D：X/Y 使用 m，航向使用 rad',
    '显式空图只能用于演示',
    '不会发送底盘运动命令',
    'TestStop',
    '栅格边界',
    '占据格',
    '换向')) {
    Assert-True $coarsePathReadmeContent.Contains($requiredReadmeText) "CoarsePath README must document: $requiredReadmeText"
}
```

- [ ] **Step 2: 运行脚本确认 README 检查失败**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 所有代码检查通过；脚本因 `CoarsePath README must document: ## P1：Clumsy 手动测试与可视化` 失败。

- [ ] **Step 3: 在 README 增加 P1 专节**

在“第一版限制”之前增加 `## P1：Clumsy 手动测试与可视化`，逐项写明：

1. 七个 MovementTest 名称及对应场景；缓存测试连续运行两次，第二次展示 `Input` 命中。
2. AMR/手动目标输入契约：世界 `X/Y(mm)`、`th(deg)`，转换成 `Pose2D` 的 m/rad；起点是车辆几何中心。
3. 空图手动目标入口只能演示坐标、路径和取消流程；现场必须提供真实障碍物快照。
4. 可视化图例：边界、抽稀格线、占据格、起点、终点及容差、前进、倒车、换向和扩大车体检查框；失败不显示部分路径。
5. `Test` 在后台规划，`TestStop` 取消令牌并清空图层；测试只显示结果，绝不发送底盘运动命令或执行路径跟踪。

- [ ] **Step 4: 运行 README 与集成检查**

Run:

```powershell
dotnet build .\ClumsyPilot\ClumsyPilot.csproj --no-restore
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 构建成功；README 和全部 P1 集成检查通过。

### Task 5: 全量回归与手动核验说明

**Files:**

- Verify: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/CoarsePathScenarioFactory.cs`
- Verify: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/Test/MovementTest.CoarsePathTest.cs`
- Verify: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/README.md`
- Verify: `ClumsyPilot/tests/verify_coarse_path_integration.ps1`

**Consumes:** Tasks 1–4 的代码、文档和脚本。

**Produces:** 通过 Debug 回归的 P1 UI 集成首个交付；不进入 Release 性能基准。

- [ ] **Step 1: 执行 Debug 构建和所有现存 P0/P1 功能脚本**

Run:

```powershell
dotnet build .\ClumsyPilot\ClumsyPilot.csproj --no-restore
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_planning_map_factory.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_planning_map_adapter.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_planning_map_image.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_planning_map_documentation.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_planning_map_test_config.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_collision.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_search.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ClumsyPilot\tests\verify_coarse_path_integration.ps1
```

Expected: 构建 0 errors；每个存在的脚本返回 0 并输出其 `passed` 消息。

- [ ] **Step 2: 手动 Clumsy 验收**

在 Clumsy 的 MovementTest 列表依次运行“粗路径-矩形绕行”和“粗路径-AMR起点手动终点(空图演示)”。检查：测试启动后界面仍可操作；图层拥有边界、格线、占据格、图例、起终点与状态；成功案例有方向区分路径和扩大车体框；点击停止后图层清空且没有任何底盘运动命令。

- [ ] **Step 3: 记录交付边界**

在完成报告中明确：P1 UI 集成已完成；下一 P1 子项目是 Release 性能、资源和确定性基准；TrapMap 迁移/清理继续排除；没有执行 Git 操作。

## 自检

- 覆盖性：Task 2 交付纯场景与单位转换；Task 3 交付后台七入口和完整视觉要素；Task 4 交付 README；Task 5 交付自动化与手动验收。规格中的空图限制、实际占据快照、停止语义、无底盘命令和不显示部分路径均有对应任务。
- 占位符：已检查任务不含未决占位、延后实现或泛化错误处理类措辞；每个实现任务均给出文件、接口、测试、命令和具体代码形状。
- 类型一致性：所有任务统一使用 `CoarsePathTestScenario`、`CoarsePathScenarioFactory.Create`、`CreateManualGoalDemo`、`CoarsePathPlanningJob`、`CoarsePathPlanningJobResult` 和 `PlanningGridMap`；AMR 输入始终是 mm+deg，核心位姿始终是 m+rad。