Files
road-compiler/.trellis/tasks/archive/2026-09/08-31-lane-maneuver-override/prd.md
T

7.1 KiB
Raw Blame History

车道转向箭头覆盖

目标

让用户能决定某条车道画什么导向箭头,而不必回去改 OSM。走 v1 override, 新增 lane-maneuver kind。

为什么是 v1 而不是 v2

这一点决定了整个设计,先说清楚。

导向箭头的内容(左转/直行/右转)来自 OSM 标签 turn:lanes:<direction>,是车道的一个离散属性;而 v2 直接编辑的锚点是 {roadId, station} 这类位置上的约束。「这条车道显示什么箭头」没有位置, 硬塞进 v2 会让锚点模型失去意义。

v1 override 里已有覆盖 OSM 派生值的先例:road kind 覆盖 laneCount、 widthMeters、sidewalkLeft/Right。转向属于同一类。

箭头的位置参数(间距、距路口距离)是另一回事,属于 v2,且还有未定的 分组决策,不在本任务内。

已确认的事实

  • turn:lanes:<direction> 或 turn:lanes 以 | 分隔,每段对应一条车道; compileLaneMarkings()(native-road.js:1520)读它,maneuvers[index] 取到本车道那段。
  • 当前 if (!explicitManeuver) continue——OSM 没标的车道不画箭头, 所以覆盖必须能给"本来没有"的车道加上箭头,不只是改已有的。
  • normalizeManeuver()(turn-lane-arrows.js:114)已导出,支持恰好 6 种取值: through / left / right / through;left / through;right / through;left;right。 它对输入排序后查表,所以 left;through 与 through;left 等价。
  • validateOverrides() 已构造 laneIds 集合(native-road.js:295), 形如 lane:<roadId>:<index>,lane-connection 是使用它的现成先例。
  • 实测当前区域有 28 条 turn:lanes:* 标签,编译出 108 个导向箭头, maneuver 取值 4 种、placement_distance_meters 恒为 6。

范围

  1. 新增 v1 override kind lane-maneuver,字段 { laneId, maneuver }。
  2. maneuver 取 6 种受支持值之一;空字符串表示不画箭头,用于移除 OSM 标了但不想要的箭头。
  3. 校验 laneId 属于已知车道;未知目标按既有 stale 机制处理,不新造一套。
  4. 覆盖优先于 OSM 标签;能给 OSM 未标注的车道新增箭头。
  5. 无覆盖时输出与当前版本字节级一致。

明确不做

  • 箭头的位置参数(间距 32m、距路口 6m)——属 v2,且分组语义未定。
  • 直行箭头(directionArrows)——那是沿车道重复摆放的另一套逻辑。
  • 客户端 UI。本任务只做编译器与 override 合同;先证明覆盖生效,再谈怎么点选。
  • 不改 OSM 源文件,不改车道数或拓扑。

验收标准

  • 对一条 OSM 已标 turn:lanes 的车道施加覆盖,编译输出的 maneuver 变为覆盖值。
  • 对一条 OSM 未标的车道施加覆盖,输出新增该车道的箭头。
  • maneuver: '' 使该车道不再输出箭头。
  • 非法 maneuver(如 'u-turn')被拒绝并报错,不静默降级。
  • 未知 laneId 按既有 stale 机制处理,与 lane-connection 行为一致。
  • 空覆盖集的编译输出与改动前字节一致(fixture 不变)。
  • npm run format:check、npm run test、npm run test:client、npm run test:client:unit、npm run build 通过。

风险与门槛

  • 门禁:先证明覆盖真的改变正式编译输出,再谈 UI。本项目已有 profile.interval 的教训——参数写了、几何阶段没读、交付了一个无效控件。
  • laneId 的稳定性与 lane-connection 同级:车道数变化会使高索引车道失效, 由既有 stale 机制兜底,本任务不新增重定位逻辑。
  • normalizeManeuver 对未知取值会原样返回拼接串(supported.get(...) || parts.join(';')), 所以校验必须在 override 层做,不能指望它兜底。

交付状态(2026-08-31)

编译器与 override 合同已完成,7 条验收标准全部通过,实测于 nantaizihu-9PTsZg(108 个导向箭头 / 28 条车道有箭头)。

场景 结果
覆盖已标注车道 through;left;right → left
给未标注车道新增 新增 3 个 part
maneuver: '' 移除 0 个
空覆盖集 与基线字节一致,fixture 未变

客户端 UI 按 PRD 明确不做。 现在只能通过 override 文件或 API 施加。 接 UI 时需要的前置:导向箭头的分组键是 lane_id + maneuver(实测 108 个 → 28 组, 每组 3 或 5 个 part),与斑马线的 crossing_node_id 不同形态, element.ts 的注册表需要扩展 groupProperty 为可组合的形式。

UI 增量(规划中,2026-09-01)

已确认事实

  • 工作台点击事件会传递所有命中的 feature,但只有开启 ?directEdit=1 时才会请求 element.ts 判断是否为可编辑元素;该注册表目前仅登记斑马线和停止线,故转向箭头 会清空元素选择。
  • 路口转向箭头的 provenance 是 native-road-turn-arrow/v1,一个逻辑箭头由 lane_id + maneuver 共同标识,并绘制为 3 或 5 个 part。
  • lane-maneuver 是 v1 离散 override,不是 v2 位置约束;它不能接入现有 ElementSelection -> handleForElement -> 拖拽手柄 路径。
  • 沿车道重复的道路方向箭头 provenance 是 native-road-direction-arrow/v1,固定为 through,由 32m 间距规则生成,当前没有对应的 override 合同。
  • 仅允许点击已生成的转向箭头无法满足“给 OSM 未标注车道新增箭头”:该车道没有 feature 可点,故 UI 还必须允许从车道中心线或道路检查器选择目标车道。

拟议范围

  1. 点击任一转向箭头 part 时,选中其完整 lane_id + maneuver 组,并在检查器展示 六种合法转向及“无箭头”。
  2. 从车道中心线进入同一编辑器,使没有现存转向箭头的车道也能新增箭头。
  3. 选择值以单一、按 laneId upsert 的 lane-maneuver override 暂存;保存并重新生成后 更新正式几何。空字符串仍表示移除。
  4. 扩展 element 注册表的分组键表达能力,但不把 v1 override 伪装成 v2 拖拽约束。

验收标准(UI)

  • 点击任一 native-road-turn-arrow/v1 part 会选中同一 lane_id + maneuver 的所有 part,且不会并入同车道的其他 maneuver。
  • 点击车道中心线能选中该车道并展示相同的转向编辑器;即使该车道当前没有转向箭头, 用户仍能选择一种转向并暂存。
  • 转向编辑器只提供编译器接受的六种规范值和“无箭头”;选择会按 laneId upsert 一个 lane-maneuver override,空字符串表示移除。
  • “保存修改”后 override 被服务端接受;“保存并重新生成”后,编译结果反映所选 maneuver 或移除,并可重新选择新的箭头。
  • native-road-direction-arrow/v1 不显示转向编辑器,32m 间距及其生成数量不变。
  • 既有斑马线、停止线选择及直接编辑手柄不回归;npm run format:check、 npm run test、npm run test:client、npm run test:client:unit、npm run build 通过。