ParkingRobot/docs/superpowers/plans/2026-07-28-coarsepath-readme-restructure.md

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 脚本中的中文编码差异：

$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 -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 实现，校验每个文件树项与说明的真实性

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

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 -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:

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

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

• Step 2: 运行 P1 文档/UI 结构检查

Run:

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

Expected: Coarse path P1 UI source checks passed.

• Step 3: 运行粗路径集成回归

Run:

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# 接口或依赖。