From f04f7d8d6adc36d6bb993bd1a04b2d447d1a5560 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=A2=81=E8=96=84=E4=BA=91?= <lby115@126.com>
Date: Wed, 22 Jul 2026 10:57:42 +0800
Subject: [PATCH] docs: define layered trap map construction

---
 ...22-trap-map-layered-construction-design.md | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-22-trap-map-layered-construction-design.md

diff --git a/docs/superpowers/specs/2026-07-22-trap-map-layered-construction-design.md b/docs/superpowers/specs/2026-07-22-trap-map-layered-construction-design.md
new file mode 100644
index 0000000..8a2f9f2
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-22-trap-map-layered-construction-design.md
@@ -0,0 +1,82 @@
+# 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`。
+- 不发送车辆运动或停止指令。