chore: save current workspace progress

docs/superpowers/specs/2026-07-27-map-documentation-design.md

@@ -0,0 +1,56 @@
+# Map 模块文档与注释设计
+
+## 目标
+
+让阅读 `ClumsyPilot/ParkrobTrajplanner/Map` 的开发者无需反查实现，即可理解模块文件职责、建图数据流和所有公共 API 的调用契约。
+
+## 交付内容
+
+### `Map/README.md`
+
+README 是 Map 模块的入口说明，只保留不会由 IDE 自动展示的模块级信息：
+
+- 当前目录树，以及每个文件的一句话职责；
+- 从 `PlanningMapRequest` 到 `PlanningGridMap` 的建图数据流；
+- 坐标系和单位约定；
+- `PlanningMapFactory` 的最小调用示例；
+- 缓存与 `SourceVersion` 的使用约束；
+- 测试、PNG 调试和旧 TrapMap 的边界。
+
+README 不复制逐个参数说明；参数的唯一权威说明位于声明处的代码注释。
+
+### `.cs` 代码注释
+
+覆盖 `Map` 内所有 `public` 类、接口、枚举、构造函数、方法和属性。注释使用可被 C# IDE 识别的 `///` XML 文档注释，但按 Python docstring 的阅读顺序组织：
+
+1. 功能：该成员做什么；
+2. 参数：名称、类型语义、单位、可空性或约束；
+3. 返回：返回对象及字段的业务意义；
+4. 注意：缓存、坐标转换、不可变性、线程安全或失败语义等调用者必须知道的约束。
+
+不为纯私有实现逐项添加重复注释；复杂算法的私有方法只在其现有说明明显不足、且会妨碍维护时补充最小必要说明。
+
+## 注释示例
+
+```csharp
+/// <summary>
+/// 创建规划地图快照。
+///
+/// 参数：
+/// - request：建图请求，包含世界范围、栅格分辨率和障碍物来源。
+///
+/// 返回：
+/// - PlanningMapBuildResult：成功时含不可变地图、来源投影结果和缓存命中类型。
+///
+/// 注意：
+/// - 应长期复用工厂实例，才能复用缓存。
+/// </summary>
+public PlanningMapBuildResult Create(PlanningMapRequest request)
+```
+
+## 验收
+
+- `Map/README.md` 可独立说明文件结构、数据流和公共入口；
+- 通过 `rg` 检查，所有 Map 公共 API 均有紧邻的中文 `///` 文档说明；
+- 现有 Map Gate 与项目编译保持通过；
+- 不修改 Map 的建图算法、缓存键或运行时行为。