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

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