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