ParkingRobot/docs/superpowers/specs/2026-07-22-trap-map-layered-construction-design.md

TrapMap 分层建图修订设计

目标

修正 MovementTest.Trapmaptest.cs 中“必须先检测到轮胎才能建立地图”的依赖倒置。基础局部地图只依赖合法的车辆位姿、车辆尺寸和地图参数；轮胎检测是可选障碍物输入，不再决定地图是否存在。

本次仍是一次性局部地图测试，不扩展 TrajPlanner，也不引入尚不存在的通用障碍物点云接口。

分层模型

地图按职责分为以下逻辑层：

1. 基础层：以车辆当前世界坐标为中心创建局部栅格，当前所有单元初始化为 Free。
2. 自车层：按照车辆长度、宽度、朝向标记本车占用区域。
3. 轮胎层：调用现有 TwoLegDetect，成功时将两个端点转换至世界坐标并膨胀为占用栅格。
4. 点云障碍层：仅作为未来扩展边界，本次不实现、不虚构输入来源。

当前 Free 的准确含义是“此栅格没有被本次已接入的占用来源标记”，并不表示传感器已经确认该区域不存在其他障碍物。代码注释必须明确这一限制，以便未来引入点云及 Unknown 状态。

数据流与执行顺序

1. 校验地图参数及车辆尺寸。
2. 从 DetourInterface.getCartLocation() 读取车辆世界位姿。
3. 立即创建以车辆为中心的局部栅格地图。
4. 标记自车占用层。
5. 尝试读取轮胎检测结果：
   • 检测成功：转换并标记两个轮胎端点。
   • 未检测到目标：轮胎层保持为空，地图仍然成功。
   • 配置缺失、检测异常或坐标非法：轮胎层保持为空，地图仍然成功，但记录降级状态和具体原因。
6. 可视化并发布地图，同时输出各层状态和统计信息。

地图的创建和发布不再等待轮胎输入。轮胎检测只影响轮胎层内容和传感器状态。

状态与错误语义

以下情况属于建图失败，不能发布地图：

• 地图分辨率、范围或安全距离非法。
• 车辆长度或宽度非法。
• 车辆世界位姿不是有限值。
• 基础地图创建、必要的自车标记或结果发布失败。

以下情况属于轮胎层降级，不导致建图失败：

• 未配置轮胎检测雷达。
• TwoLegDetect 没有检测到目标。
• 检测调用抛出异常。
• 返回的端点或转换后的世界坐标非法。

输出应区分：

• Succeeded：基础地图是否成功生成。
• InputSource：本次实际启用的障碍来源。
• 轮胎层状态：已标记、未检测到或检测异常。
• 轮胎层状态说明：未标记或异常的具体原因。

“未检测到目标”与“检测器异常”都产生空轮胎层，但日志语义不能混同：前者表示本次没有轮胎投影，后者表示轮胎信息不可用。

数据结构边界

本次可以继续使用最终合并后的 GridMapData.Cells，无需提前实现完整的多层栅格容器。分层通过独立的填充步骤、来源状态和统计实现，避免为尚未接入的点云设计过度复杂的数据模型。

未来点云接入时，应新增独立的点云转换/栅格化步骤，再合并到最终占用结果；不得把原始点云读取逻辑塞入轮胎检测函数。

测试要求

至少覆盖以下行为：

1. 位姿和地图参数合法、轮胎检测无目标时，地图成功且轮胎障碍数为零。
2. 轮胎检测配置缺失或调用异常时，地图仍成功，并记录降级原因。
3. 轮胎检测成功时，两个端点被转换并投影为占用栅格。
4. 位姿或地图参数非法时，地图失败且不发布半成品。
5. 源码契约确认建图发生在轮胎检测之前，且不存在实车模式模拟障碍回退。
6. 注释明确当前 Free 不等于传感器确认无障碍，并标明未来点云/Unknown 扩展方向。

非目标

• 不实现持续更新或历史地图融合。
• 不实现全局大地图。
• 不接入未经现有代码验证的点云 API。
• 不修改或展开 TrajPlanner。
• 不发送车辆运动或停止指令。