# 车道转向箭头覆盖 ## 目标 让用户能决定某条车道画什么导向箭头,而不必回去改 OSM。走 **v1 override**, 新增 `lane-maneuver` kind。 ## 为什么是 v1 而不是 v2 这一点决定了整个设计,先说清楚。 导向箭头的**内容**(左转/直行/右转)来自 OSM 标签 `turn:lanes:`,是车道的一个**离散属性**;而 v2 直接编辑的锚点是 `{roadId, station}` 这类**位置上的约束**。「这条车道显示什么箭头」没有位置, 硬塞进 v2 会让锚点模型失去意义。 v1 override 里已有覆盖 OSM 派生值的先例:`road` kind 覆盖 `laneCount`、 `widthMeters`、`sidewalkLeft/Right`。转向属于同一类。 **箭头的位置参数(间距、距路口距离)是另一回事**,属于 v2,且还有未定的 分组决策,不在本任务内。 ## 已确认的事实 - `turn:lanes:` 或 `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::`,`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 层做,不能指望它兜底。