Files
road-compiler/.trellis/tasks/08-31-lane-maneuver-override/prd.md
T
que01andClaude Opus 5 8b84166e6f chore(task): record lane-maneuver delivery and the UI prerequisite
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>
2026-08-31 18:02:27 +08:00

87 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 车道转向箭头覆盖
## 目标
让用户能决定某条车道画什么导向箭头,而不必回去改 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` 为可组合的形式。