# CoarsePath README 结构化重构 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:** 将 CoarsePath README 重构为与 Map README 相同的“结构—数据流—契约—最小示例—分步指南—常见错误”说明方式，同时保留准确的 P0/P1 边界。

**Architecture:** 保持所有生产代码不变。先为 README 的结构性事实增加稳定的 ASCII 文本断言，再将现有 README 的正确内容重组为面向调用者的模块说明，最后运行文档、构建与集成回归，证明这只是文档交付。

**Tech Stack:** Markdown、PowerShell、.NET `netstandard2.0` Debug 构建、现有 CoarsePath 验证脚本。

## Global Constraints

- 只修改 `CoarsePath/README.md` 与其文档断言；不得改动 Map、CoarsePath、P1 UI 或测试场景的运行行为。
- README 只陈述当前已实现并经自动化验证的 P0/P1 能力；实际 Clumsy 的人工视觉验收仍要明确为待执行。
- 业务调用示例固定使用 `CoarsePathPlanningService.Plan(job, cancellationToken)`；不得鼓励 UI 或调用方直接拼接搜索组件。
- Map 障碍物投影、栅格化和缓存细节只链接到 `../Map/README.md`，不复制为 CoarsePath 实现说明。
- 坐标说明必须保持：Map 输入为 mm，核心位姿/路径为 m，核心航向为 rad；P1 UI 的 AMR 输入航向为 deg 并在边界转换。
- 显式空图只能描述为 P1 单位/可视化演示，不能描述为真实作业地图。
- 不恢复、清理或迁移 TrapMap 文件或旧 TrapMap 验证脚本；不执行 Git 状态、差异、提交或重置操作。

---

## 文件结构

| 文件 | 修改职责 |
| --- | --- |
| `ClumsyPilot/ParkrobTrajplanner/CoarsePath/README.md` | 重组现有 P0/P1 内容，加入实际目录树、规划数据流、分步指南与常见错误。 |
| `ClumsyPilot/tests/verify_coarse_path_ui.ps1` | 用 ASCII 关键字保护 README 的结构、核心边界和 P1 说明。 |

### Task 1: 为 README 重构建立失败的结构断言

**Files:**

- Modify: `ClumsyPilot/tests/verify_coarse_path_ui.ps1`
- Verify later: `ClumsyPilot/ParkrobTrajplanner/CoarsePath/README.md`

**Consumes:** 现有 `$readmePath`、`$readme`、`Assert-True` 及 P1 UI 源码检查。

**Produces:** 文档结构保护；README 缺少新的 Map 风格章节或 P1 边界时脚本失败。

- [ ] **Step 1: 在现有 README 断言后加入目标结构的失败检查**

在当前 `$requiredText` 循环之后插入以下 PowerShell。所有匹配项保持 ASCII，避免 Windows PowerShell 无 BOM 脚本中的中文编码差异：

```powershell
$readmeStructure = @(
    'File Structure',
    'Planning Data Flow',
    'Build Status and Stop',
    'Coordinates and Units',
    'Minimal Call Example',
    'Cache and SourceVersion',
    'Detailed Usage Guide',
    'P1 Manual Tests and Visualization',
    'Common Errors',
    'First-Version Limits',
    'CoarsePathPlanningService.Plan(job, cancellationToken)',
    'CoarsePathPlanningJob',
    'PlanningGridMap',
    'SourceVersion',
    'CoarsePathPlanningV1',
    'CancellationTokenSource',
    'NoFeasiblePath',
    'IsGearSwitchPoint',
    '../Map/README.md'
)
foreach ($requiredText in $readmeStructure) {
    Assert-True ($readme.Contains($requiredText)) "Restructured CoarsePath README must document $requiredText."
}
```

- [ ] **Step 2: 运行脚本确认 README 仍缺少新结构**

Run:

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

Expected: `Restructured CoarsePath README must document File Structure.`；源码 UI 断言仍通过。

### Task 2: 重构 CoarsePath README 的模块说明与调用文档

**Files:**

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

**Consumes:** Map README 的组织方式；现有 CoarsePath README 的真实 P0/P1 契约；`CoarsePathPlanningService.Plan(job, cancellationToken)`。

**Produces:** 一份可从零开始阅读的 CoarsePath 模块说明，内容与当前实现一致。

- [ ] **Step 1: 用 Map 风格的顶层章节替换现有 README 的章节顺序**

保留 README 标题 `# CoarsePath 粗路径规划（P0/P1）`，然后按以下顺序重新组织内容；将每个二级标题同时写为中文说明和括号中的 ASCII 稳定标识，例如 `## 文件结构（File Structure）`，使人类读者与 Task 1 断言都能使用：

1. `## 模块说明（Module Overview）`：说明 Map 提供只读快照，CoarsePath 输出已复核的粗路径；唯一业务入口是 `CoarsePathPlanningService.Plan(job, cancellationToken)`；列出不负责的控制、速度、实时重规划等职责。
2. `## 文件结构（File Structure）`：使用 `text` 目录树列出实际 `Contracts/`、`Vehicle/`、`Search/`、`Output/`、`Facade/` 与 `Test/` 文件，逐项写出与当前目录对应的职责。
3. `## 规划数据流（Planning Data Flow）`：画出 `CoarsePathPlanningJob -> CoarsePathPlanningService -> PlanningMapFactory.Create -> PlanningGridMap -> HybridAStarPlanner -> PlanningResult -> CoarsePathPlanningJobResult`；在失败分支注明地图失败不启动搜索。
4. `## 构建状态与停止（Build Status and Stop）`：说明 `MapResult` 和 `PlanningResult` 必须一起处理，解释 `Success`、`Cancelled`、`SearchTimeout`、`NoFeasiblePath` 与空路径规则。
5. `## 坐标与单位（Coordinates and Units）`：用表格列出地图 mm、`Pose2D`/路径 m、核心航向 rad、P1 AMR 输入 deg；明确起点为车身几何中心和安全余量由 `VehicleParameters.SafetyMarginMeters` 表达。
6. `## 最小调用示例（Minimal Call Example）`：保留并精简当前服务调用示例；包含 `PlanningMapRequest`、`Pose2D`、`VehicleParameters`、`HybridAStarConfiguration`、`MapResult` 与 `PlanningResult` 的失败处理。
7. `## 缓存与 SourceVersion（Cache and SourceVersion）`：说明服务长期存活、`Input`/`Occupancy`/`None` 缓存层级，及来源内容变更必须递增 `SourceVersion`。
8. `## 详细使用指南（Detailed Usage Guide）`：用六步小节解释长期服务、准备地图请求、填写起终点、填写车辆、调整搜索配置、调用及消费路径/方向段；链接 `../Map/README.md` 说明障碍物来源和栅格化。
9. `## P1 手动测试与可视化（P1 Manual Tests and Visualization）`：包含七个 MovementTest 的场景表、`CoarsePathPlanningTest` 的 `getCartLocation`/手动目标转换、`CancellationTokenSource`/`Task.Run`/`TestStop` 停止语义、`CoarsePathPlanningV1` 图层及颜色图例。明确人工视觉验收尚待在实际 Clumsy 中执行。
10. `## 常见错误（Common Errors）`：以“现象 / 原因 / 处理”表格写入：mm 当作 m、deg 当作 rad、`SourceVersion` 未递增、隐式空图、未处理非成功结果、把粗路径当作底盘可执行轨迹。
11. `## 第一版限制（First-Version Limits）`：保留并归并路径平滑、速度/时间轨迹、底盘控制、实时重规划、真实作业地图、Release 基准等明确非目标。

- [ ] **Step 2: 对照实际目录和 P1 实现，校验每个文件树项与说明的真实性**

确认目录树只引用下列已存在组件：

```text
Contracts/: Pose2D, PlanningRequest, PlanningResult, PlanningStatus,
           CoarsePathPoint, PathSegment, VehicleParameters, HybridAStarConfiguration
Vehicle/: VehicleKinematics, VehicleFootprint, FootprintCollisionChecker,
          OrientedRectangleCellIntersection
Search/: BinaryMinHeap, GridDijkstraHeuristic, GoalToleranceChecker,
         MotionPrimitive, MotionPrimitiveGenerator, SearchCostCalculator,
         HybridAStarNode, HybridAStarNodeKey, HybridAStarSearch
Output/: PathBacktracker, CoarsePathAssembler, CoarsePathValidator
Facade/: CoarsePathPlanningJob, CoarsePathPlanningJobResult,
         CoarsePathPlanningService, PlanningDebugOptions, IPlanningDebugSink
Test/: CoarsePathScenarioFactory, MovementTest.CoarsePathTest
```

不要在 README 中承诺不存在的平滑器、控制器、实时数据源或 Release 基准。

- [ ] **Step 3: 运行文档结构检查确认通过**

Run:

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

Expected: `Coarse path P1 UI source checks passed.`

### Task 3: 验证文档重构没有影响 P0/P1 行为

**Files:**

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

**Consumes:** Tasks 1–2 的 README 与断言。

**Produces:** 从最终工作区获得的文档、构建和集成验证证据。

- [ ] **Step 1: 构建项目**

Run:

```powershell
dotnet build .\ClumsyPilot\ClumsyPilot.csproj --no-restore
```

Expected: `0 个错误`；允许项目已有的两条过时 API 警告。

- [ ] **Step 2: 运行 P1 文档/UI 结构检查**

Run:

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

Expected: `Coarse path P1 UI source checks passed.`

- [ ] **Step 3: 运行粗路径集成回归**

Run:

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

Expected: 依次输出 `Coarse path integration checks passed.`、`Coarse path facade checks passed.` 与 `Coarse path P1 scenario checks passed.`。

## 自检

- **规格覆盖：** Task 2 覆盖设计中的十个 README 章节、P0/P1 已完成边界、Map 链接、单位、空图限制与人工验收状态；Task 1 保护可自动检查的结构事实；Task 3 给出最终证据。
- **完整性检查：** 本计划不含未决实现、泛化错误处理或未命名的验证步骤；每项改动均有文件路径、具体内容与命令。
- **一致性：** 所有调用名、状态名、场景工厂、P1 图层和坐标单位均与现有 CoarsePath 代码一致；计划不引入新 C# 接口或依赖。