docs: define workstation-bounded trap map

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

@@ -2,32 +2,56 @@
 
 ## 目标
 
-修正 `MovementTest.Trapmaptest.cs` 中“必须先检测到轮胎才能建立地图”的依赖倒置。基础局部地图只依赖合法的车辆位姿、车辆尺寸和地图参数；轮胎检测是可选障碍物输入，不再决定地图是否存在。
+修正 `MovementTest.Trapmaptest.cs` 中“必须先检测到轮胎才能建立地图”的依赖倒置，并将随车固定窗口改为任务级世界坐标栅格。基础地图只依赖合法的车辆位姿、车辆尺寸、工作站世界坐标和地图参数；轮胎检测是可选障碍物输入，不再决定地图是否存在。
 
-本次仍是一次性局部地图测试，不扩展 `TrajPlanner`，也不引入尚不存在的通用障碍物点云接口。
+本次仍是一次性地图测试，不扩展 `TrajPlanner`，也不引入尚不存在的通用障碍物点云接口。该地图覆盖当前车辆到目标工作站的任务范围，不宣称覆盖整个停车场的永久 SLAM 全局地图。
+
+## 地图范围
+
+目标工作站使用与 `DetourInterface.getCartLocation()` 完全相同的绝对世界坐标系，单位为 mm。第一版默认可调参数为：
+
+- `WorkstationX = 10000 mm`
+- `WorkstationY = 0 mm`
+- `MapMarginX = 3000 mm`
+- `MapMarginY = 3000 mm`
+
+读取车辆几何中心 `(CarX, CarY)` 后，地图边界按以下方式计算：
+
+```text
+XMin = min(CarX, WorkstationX) - MapMarginX
+XMax = max(CarX, WorkstationX) + MapMarginX
+YMin = min(CarY, WorkstationY) - MapMarginY
+YMax = max(CarY, WorkstationY) + MapMarginY
+```
+
+工作站坐标和 X/Y 冗余必须可配置，不能继续用一个随车半边长参数控制地图。边界采用世界坐标轴对齐矩形，保证车辆点、工作站点及四周冗余都在地图内。
+
+实现必须校验坐标、冗余、计算后的边界、行列数与总栅格数量，拒绝非有限值、负冗余、退化边界和可能造成异常内存分配的超大地图。
 
 ## 分层模型
 
 地图按职责分为以下逻辑层：
 
-1. 基础层：以车辆当前世界坐标为中心创建局部栅格，当前所有单元初始化为 `Free`。
+1. 基础层：按车辆—工作站包围矩形及 X/Y 冗余创建任务级世界坐标栅格，当前所有单元初始化为 `Free`。
 2. 自车层：按照车辆长度、宽度、朝向标记本车占用区域。
-3. 轮胎层：调用现有 `TwoLegDetect`，成功时将两个端点转换至世界坐标并膨胀为占用栅格。
-4. 点云障碍层：仅作为未来扩展边界，本次不实现、不虚构输入来源。
+3. 目标层：记录并可视化工作站位置；目标点不是障碍物，不写入占用栅格。
+4. 轮胎层：调用现有 `TwoLegDetect`，成功时将两个端点转换至世界坐标并膨胀为占用栅格。
+5. 点云障碍层：仅作为未来扩展边界，本次不实现、不虚构输入来源。
 
 当前 `Free` 的准确含义是“此栅格没有被本次已接入的占用来源标记”，并不表示传感器已经确认该区域不存在其他障碍物。代码注释必须明确这一限制，以便未来引入点云及 `Unknown` 状态。
 
 ## 数据流与执行顺序
 
-1. 校验地图参数及车辆尺寸。
+1. 校验地图分辨率、工作站坐标、X/Y 冗余及车辆尺寸。
 2. 从 `DetourInterface.getCartLocation()` 读取车辆世界位姿。
-3. 立即创建以车辆为中心的局部栅格地图。
-4. 标记自车占用层。
-5. 尝试读取轮胎检测结果：
+3. 根据车辆点和工作站点计算包围矩形，校验最终尺寸和栅格总量。
+4. 立即创建任务级世界坐标栅格地图。
+5. 标记自车占用层并记录工作站目标层。
+6. 尝试读取轮胎检测结果：
    - 检测成功：转换并标记两个轮胎端点。
    - 未检测到目标：轮胎层保持为空，地图仍然成功。
    - 配置缺失、检测异常或坐标非法：轮胎层保持为空，地图仍然成功，但记录降级状态和具体原因。
-6. 可视化并发布地图，同时输出各层状态和统计信息。
+7. 可视化并发布地图，同时输出边界、工作站、各层状态和统计信息。
 
 地图的创建和发布不再等待轮胎输入。轮胎检测只影响轮胎层内容和传感器状态。
 
@@ -36,6 +60,8 @@
 以下情况属于建图失败，不能发布地图：
 
 - 地图分辨率、范围或安全距离非法。
+- 工作站世界坐标或 X/Y 冗余非法。
+- 计算后的行列数或总栅格数量超过安全上限。
 - 车辆长度或宽度非法。
 - 车辆世界位姿不是有限值。
 - 基础地图创建、必要的自车标记或结果发布失败。
@@ -66,17 +92,19 @@
 
 至少覆盖以下行为：
 
-1. 位姿和地图参数合法、轮胎检测无目标时，地图成功且轮胎障碍数为零。
+1. 位姿、工作站和地图参数合法、轮胎检测无目标时，地图成功且轮胎障碍数为零。
 2. 轮胎检测配置缺失或调用异常时，地图仍成功，并记录降级原因。
 3. 轮胎检测成功时，两个端点被转换并投影为占用栅格。
-4. 位姿或地图参数非法时，地图失败且不发布半成品。
-5. 源码契约确认建图发生在轮胎检测之前，且不存在实车模式模拟障碍回退。
-6. 注释明确当前 `Free` 不等于传感器确认无障碍，并标明未来点云/`Unknown` 扩展方向。
+4. 边界严格由车辆点、工作站点及各轴冗余计算，并同时包含两个点。
+5. 工作站可视化但不增加占用栅格数量。
+6. 位姿、工作站、冗余、地图参数或总栅格数量非法时，地图失败且不发布半成品。
+7. 源码契约确认建图发生在轮胎检测之前，且不存在实车模式模拟障碍回退。
+8. 注释明确当前 `Free` 不等于传感器确认无障碍，并标明未来点云/`Unknown` 扩展方向。
 
 ## 非目标
 
 - 不实现持续更新或历史地图融合。
-- 不实现全局大地图。
+- 不读取或声称生成完整停车场 SLAM 静态地图；本次“全局”仅指车辆和工作站共享的世界坐标任务范围。
 - 不接入未经现有代码验证的点云 API。
 - 不修改或展开 `TrajPlanner`。
 - 不发送车辆运动或停止指令。