# CoarsePath README 结构化重构设计

## 目标

将 `ClumsyPilot/ParkrobTrajplanner/CoarsePath/README.md` 重构为与 `Map/README.md` 一致的说明风格，使调用者能够从模块职责、文件位置和数据流开始，逐步理解粗路径的调用、状态处理、P1 手动测试与明确的非目标。

本次只重构文档内容与现有文档检查；不改变 `Map`、`CoarsePath`、P1 UI 或任何测试场景的运行行为。

## 当前事实

- `Map` 负责障碍物来源、栅格化、不可变 `PlanningGridMap` 与缓存；它是粗路径的输入依赖。
- `CoarsePath` 已具备 P0 核心：车辆扩大足迹碰撞、前进/倒车原语、Dijkstra 启发式、Hybrid A*、路径回溯、最终复核与业务门面。
- P1 已具备：六个固定场景、AMR 位姿与手动终点空图演示、后台取消、Painter 结果可视化与 UI 结构检查。
- 尚不包含平滑、速度/时间轨迹、底盘控制、实时重规划、真实作业障碍物接入与 Release 基准。

## README 目标结构

1. **模块说明**：定义 `CoarsePath` 的输入、输出、唯一业务入口与职责边界。
2. **文件结构**：按 `Contracts`、`Vehicle`、`Search`、`Output`、`Facade`、`Test` 列出实际文件及职责。
3. **规划数据流**：说明 `CoarsePathPlanningJob` 经服务、Map 快照、Hybrid A* 到 `PlanningResult` 的固定路径；明确地图失败不会启动搜索。
4. **状态、单位与安全边界**：集中说明 mm/m、deg/rad、车辆安全外扩、取消/超时和“非成功不发布部分路径”。
5. **最小调用示例**：沿用现有可编译门面调用，展示成功、地图失败和规划失败的处理方式。
6. **缓存与 SourceVersion**：解释长期持有服务、`Input`/`Occupancy`/`None` 缓存层级及版本递增责任。
7. **详细使用指南**：依次说明长期服务、准备地图请求、车辆和搜索参数、调用门面、消费路径与方向段。
8. **P1 测试与调试**：集中说明七个 MovementTest、AMR 手动终点单位边界、后台停止和 Painter 图例。
9. **常见错误**：用“现象 / 原因 / 处理”表格覆盖单位混用、遗漏 `SourceVersion`、隐式空图、错误处理失败结果、将粗路径当作控制轨迹等问题。
10. **第一版限制**：保留不属于 P0/P1 的能力清单。

## 内容约束

- 仅记录已实现且已验证的行为；不把 P1 计划或人工验收说成已完成能力。
- 固定使用 `CoarsePathPlanningService.Plan(job, cancellationToken)` 作为唯一业务调用示例；不鼓励 UI 直接组装搜索组件。
- 保留 `Map/README.md` 链接，避免复制地图障碍物和栅格化的详细说明。
- P1 手动终点必须明确是显式空图演示，不能代表现场无障碍；当前 AMR 位姿为车辆几何中心，输入在 UI 边界从 mm/deg 转为 m/rad。
- 使用中文说明、目录树、数据流图、参数表、代码示例和常见错误表，保持 Map README 的信息密度与顺序。

## 验证

- 扩展 `ClumsyPilot/tests/verify_coarse_path_ui.ps1`，以 ASCII 稳定标识检查 README 含有新的主要章节、核心门面、数据流、P1 入口、单位、停止语义、非部分路径和限制边界。
- 运行 README 的 P1 UI 检查，以及现有 Debug 构建和粗路径集成检查；文档改动不应影响生产代码或 P0 行为。

## 非目标

- 不重写或迁移 `Map/README.md`。
- 不新增、删除或改名 C# 类型、场景、MovementTest 或测试脚本。
- 不恢复、清理或迁移 TrapMap 及其旧验证脚本。