All seven criteria pass against a live area. Notes what a UI would need first: turn arrows group by lane plus maneuver, a two-field key, where crosswalks and stop lines group by a single property — so the element registry's groupProperty has to become composable before arrows can join it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
87 lines
4.6 KiB
Markdown
87 lines
4.6 KiB
Markdown
# 车道转向箭头覆盖
|
||
|
||
## 目标
|
||
|
||
让用户能决定某条车道画什么导向箭头,而不必回去改 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 源文件,不改车道数或拓扑。
|
||
|
||
## 验收标准
|
||
|
||
- [x] 对一条 OSM 已标 `turn:lanes` 的车道施加覆盖,编译输出的 `maneuver` 变为覆盖值。
|
||
- [x] 对一条 OSM **未标**的车道施加覆盖,输出**新增**该车道的箭头。
|
||
- [x] `maneuver: ''` 使该车道不再输出箭头。
|
||
- [x] 非法 `maneuver`(如 `'u-turn'`)被拒绝并报错,不静默降级。
|
||
- [x] 未知 `laneId` 按既有 stale 机制处理,与 `lane-connection` 行为一致。
|
||
- [x] 空覆盖集的编译输出与改动前字节一致(fixture 不变)。
|
||
- [x] `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` 为可组合的形式。
|