chore(task): archive lane maneuver override

This commit is contained in:
que01 committed 2026-09-01 09:17:57 +08:00
1 parent e48eb15827
commit 2415733597
6 files changed
+2 -2

No files matched your search

@@ -0,0 +1,2 @@
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Verify that new lane selection does not write baseline layers or join the drag-handle path."}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Verify the staged override remains a compiler-valid lane-maneuver payload."}
@@ -0,0 +1,48 @@
# Lane Maneuver UI Design
## Boundary
This increment exposes the existing v1 `lane-maneuver` override in the workbench.
It changes neither compiler validation nor the placement algorithms. In particular,
`native-road-direction-arrow/v1` remains display-only because it represents repeated
straight-ahead markings controlled by a separate interval policy.
## Selection Model
`edit/element.ts` remains the sole conversion point from clicked GeoJSON properties
to a logical element. Its registry gains a turn-arrow entry whose group key is the
ordered tuple `[lane_id, maneuver]`; the key is serialized with a dedicated, stable
separator rather than inferred from `native_id`. This groups the 3/5 polygon parts
of one visual arrow without merging arrows from different maneuvers on the same lane.
The current crosswalk/stop-line `ElementSelection` is junction-control-specific.
Turn arrows instead produce a lane selection carrying `laneId`, `maneuver`, and the
group feature ids. They deliberately do not call `handleForElement` or create an
outline/drag target: changing a maneuver is a v1 discrete override rather than a
v2 spatial constraint.
Lane centerlines already publish `native_id` equal to the compiler lane id. The
click handler recognizes that id and creates the same lane selection, with the
current maneuver resolved from the stored/staged override first, then from the
clicked turn arrow if present, otherwise empty. That makes an unmarked lane editable.
## Inspector And Save Flow
The inspector owns the discrete selector. It receives the selected lane and the
effective override list, offers the compiler's six exact canonical values plus
empty-string removal, and stages one deterministic id per lane. The existing
`stage` function replaces entries with equal ids, so a lane has exactly one pending
override and save/recompile continues through the established API path.
This is intentionally not a direct-edit (`EditSession`) operation: no preview
endpoint consumes lane-maneuver and a client-side visual preview would disagree with
the authoritative compiler output. The existing save-then-recompile copy remains
the user-visible boundary.
## Tests
Pure tests cover tuple grouping, part selection, lane-centerline selection and
non-selection of direction arrows. A component-level test is unnecessary for the
existing app test style; the inspector's emitted object is kept simple enough to
exercise by extracting a pure override builder if needed. Typecheck and build cover
the wiring.
@@ -0,0 +1,2 @@
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Preserve direct-edit layer and handle ownership while adding a separate v1 discrete selection path."}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Keep the UI's staged override shape aligned with the compiler and API contract."}
@@ -0,0 +1,16 @@
# Implementation Plan
1. Generalize the element registry's group-key reader and add a lane-maneuver
selection type for turn arrows and lane centerlines.
2. Wire map clicks to preserve the existing control-element path while selecting
lane arrows or centerlines through the new path.
3. Add an inspector selector that stages a lane-maneuver override with canonical
values and an explicit removal value.
4. Add focused element tests for multi-property grouping and unmarked-lane entry.
5. Run formatting, server tests, client type/unit tests, and production build.
## Rollback
The UI is isolated to `workbench/client/src/edit/element.ts`, `App.tsx`, and its
unit tests. Reverting those files restores the previous display-only arrow behavior;
the compiler's already-shipped v1 override contract remains untouched.
@@ -0,0 +1,125 @@
# 车道转向箭头覆盖
## 目标
让用户能决定某条车道画什么导向箭头,而不必回去改 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` 通过。
@@ -0,0 +1,26 @@
{
"id": "lane-maneuver-override",
"name": "lane-maneuver-override",
"title": "车道转向箭头覆盖",
"description": "v1 override 新增 lane-maneuver:覆盖 OSM turn:lanes,决定某条车道画什么导向箭头",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-31",
"completedAt": "2026-09-01",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
"meta": {}
}