From 335c8ea68ab0c40db891e2ab1413dc2f9beb9ad5 Mon Sep 17 00:00:00 2001 From: que01 Date: Mon, 31 Aug 2026 18:00:53 +0800 Subject: [PATCH] feat: override which turn arrow a lane shows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The arrow on a lane came from the OSM turn:lanes tag with no way to change it, and a lane the tag skipped got no arrow at all. lane-maneuver is a v1 override that sets it. v1 rather than a v2 constraint, because "which arrow" is a discrete attribute of a lane with no station to anchor to, while every v2 anchor is positional. The existing road override already covers OSM-derived values this way — laneCount, width, sidewalks — and this is the same kind of thing. Arrow *placement* is the positional half and stays out; it also still has an open question about whether a group is a lane or a single arrow. Three behaviours, each measured against compiled output: an override replaces the tag's maneuver, it adds arrows to a lane the tag never marked, and '' removes one the tag asked for. The empty string is therefore distinguished from "no override" rather than falling through to the tag. An empty override set leaves the arrows byte-identical and the fixtures untouched. Validation lists the accepted maneuvers and rejects anything else, including correctly-spelled components in the wrong order. It cannot be left to normalizeManeuver(), which returns unrecognised input unchanged — a typo would otherwise reach the template lookup and silently produce no arrow. Co-Authored-By: Claude Opus 5 (1M context) --- .../task.json | 3 +- .../08-31-lane-maneuver-override/check.jsonl | 1 + .../implement.jsonl | 1 + .../tasks/08-31-lane-maneuver-override/prd.md | 69 +++++++++++++++++++ .../08-31-lane-maneuver-override/task.json | 26 +++++++ src/compile/native-road.js | 36 +++++++++- test/index.js | 39 +++++++++++ 7 files changed, 173 insertions(+), 2 deletions(-) create mode 100644 .trellis/tasks/08-31-lane-maneuver-override/check.jsonl create mode 100644 .trellis/tasks/08-31-lane-maneuver-override/implement.jsonl create mode 100644 .trellis/tasks/08-31-lane-maneuver-override/prd.md create mode 100644 .trellis/tasks/08-31-lane-maneuver-override/task.json diff --git a/.trellis/tasks/08-26-direct-manipulation-road-editor/task.json b/.trellis/tasks/08-26-direct-manipulation-road-editor/task.json index ce214b1..02470ef 100644 --- a/.trellis/tasks/08-26-direct-manipulation-road-editor/task.json +++ b/.trellis/tasks/08-26-direct-manipulation-road-editor/task.json @@ -28,7 +28,8 @@ "08-28-junction-control-offsets", "08-28-crosswalk-element-editor", "08-31-parameter-panel-binding", - "08-31-constraint-range-validation" + "08-31-constraint-range-validation", + "08-31-lane-maneuver-override" ], "parent": null, "relatedFiles": [ diff --git a/.trellis/tasks/08-31-lane-maneuver-override/check.jsonl b/.trellis/tasks/08-31-lane-maneuver-override/check.jsonl new file mode 100644 index 0000000..9dd3234 --- /dev/null +++ b/.trellis/tasks/08-31-lane-maneuver-override/check.jsonl @@ -0,0 +1 @@ +{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."} diff --git a/.trellis/tasks/08-31-lane-maneuver-override/implement.jsonl b/.trellis/tasks/08-31-lane-maneuver-override/implement.jsonl new file mode 100644 index 0000000..9dd3234 --- /dev/null +++ b/.trellis/tasks/08-31-lane-maneuver-override/implement.jsonl @@ -0,0 +1 @@ +{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."} diff --git a/.trellis/tasks/08-31-lane-maneuver-override/prd.md b/.trellis/tasks/08-31-lane-maneuver-override/prd.md new file mode 100644 index 0000000..2d90311 --- /dev/null +++ b/.trellis/tasks/08-31-lane-maneuver-override/prd.md @@ -0,0 +1,69 @@ +# 车道转向箭头覆盖 + +## 目标 + +让用户能决定某条车道画什么导向箭头,而不必回去改 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 层做,不能指望它兜底。 diff --git a/.trellis/tasks/08-31-lane-maneuver-override/task.json b/.trellis/tasks/08-31-lane-maneuver-override/task.json new file mode 100644 index 0000000..46832e7 --- /dev/null +++ b/.trellis/tasks/08-31-lane-maneuver-override/task.json @@ -0,0 +1,26 @@ +{ + "id": "lane-maneuver-override", + "name": "lane-maneuver-override", + "title": "车道转向箭头覆盖", + "description": "v1 override 新增 lane-maneuver:覆盖 OSM turn:lanes,决定某条车道画什么导向箭头", + "status": "in_progress", + "dev_type": null, + "scope": null, + "package": null, + "priority": "P2", + "creator": "dingkang", + "assignee": "dingkang", + "createdAt": "2026-08-31", + "completedAt": null, + "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": {} +} \ No newline at end of file diff --git a/src/compile/native-road.js b/src/compile/native-road.js index afd717d..c347c0b 100644 --- a/src/compile/native-road.js +++ b/src/compile/native-road.js @@ -51,6 +51,17 @@ const DEFAULT_WIDTHS = { service: 4, }; const DEFAULT_SIDEWALK_WIDTH_METERS = 2; +// The maneuvers `turn-lane-arrows.js` has templates for. `normalizeManeuver()` +// returns unknown input unchanged rather than failing, so an override has to be +// checked here — it cannot lean on normalisation to reject a typo. +const SUPPORTED_MANEUVERS = new Set([ + 'through', + 'left', + 'right', + 'through;left', + 'through;right', + 'through;left;right', +]); const DIRECTION_ARROW_INTERVAL_METERS = 32; const DIRECTION_ARROW_ENDPOINT_BUFFER_METERS = 14; const STOP_LINE_MAX_APPROACH_DISTANCE_METERS = 25; @@ -264,6 +275,8 @@ function staleOverrideTarget(item, sets) { if (item.kind === 'road' && typeof item.roadId === 'string' && !sets.roadIds.has(item.roadId)) return item.roadId; if (item.kind === 'lane-separator-style' && typeof item.roadId === 'string' && !sets.roadIds.has(item.roadId)) return item.roadId; + if (item.kind === 'lane-maneuver' && typeof item.laneId === 'string' && !sets.laneIds.has(item.laneId)) + return item.laneId; if (item.kind === 'edge-line-style' && typeof item.roadId === 'string' && !sets.directionalRoadIds.has(item.roadId)) return item.roadId; if (item.kind === 'center-line-style' && typeof item.segmentId === 'string' && !sets.segmentIds.has(item.segmentId)) @@ -325,6 +338,16 @@ function validateOverrides(value, model, options = {}) { throw new Error(`Invalid road override ${key}.`); for (const key of ['sidewalkLeft', 'sidewalkRight']) if (item[key] !== undefined && typeof item[key] !== 'boolean') throw new Error(`Invalid road override ${key}.`); + } else if (item.kind === 'lane-maneuver') { + if (typeof item.laneId !== 'string' || (laneIds && !laneIds.has(item.laneId))) + throw new Error(`Unknown lane maneuver override target: ${item.laneId}`); + // '' is meaningful: it removes an arrow OSM asked for. Anything else must be + // a maneuver there is a template for. + if (typeof item.maneuver !== 'string' || (item.maneuver !== '' && !SUPPORTED_MANEUVERS.has(item.maneuver))) + throw new Error( + `Invalid lane maneuver override: ${item.maneuver}. Use '' to remove an arrow, or one of ` + + `${[...SUPPORTED_MANEUVERS].join(', ')} — components must be in that order.`, + ); } else if (item.kind === 'junction-connection') { if ( typeof item.fromEndpointId !== 'string' || @@ -1521,7 +1544,12 @@ function compileLaneMarkings(model, overrides, lanes, diagnostics, junctionPlans const maneuvers = turns ? String(turns).split('|') : []; for (let index = 0; index < roadLanes.length; index += 1) { const lane = roadLanes[index]; - const explicitManeuver = maneuvers[index]; + // An override wins over the tag, and can put an arrow on a lane OSM never + // marked — the tag being absent is exactly the case a user needs to fix. + // An empty string is a deliberate "no arrow here", so it is distinguished + // from "no override" rather than falling through to the tag. + const override = lane ? laneManeuverOverride(overrides, lane.id) : undefined; + const explicitManeuver = override !== undefined ? override : maneuvers[index]; if (!explicitManeuver) continue; const maneuver = normalizeManeuver(explicitManeuver); if (!lane) { @@ -2338,6 +2366,12 @@ function compileConnectors(model, lanes, diagnostics, overrides, junctionPlans) } return { features, movements }; } +/** The maneuver an override sets for a lane, or `undefined` when none applies. */ +function laneManeuverOverride(overrides, laneId) { + const item = (overrides?.overrides || []).find((entry) => entry.kind === 'lane-maneuver' && entry.laneId === laneId); + return item ? item.maneuver : undefined; +} + function laneOverride(overrides, fromLaneId, toLaneId) { return overrides.overrides.find( (item) => item.kind === 'lane-connection' && item.fromLaneId === fromLaneId && item.toLaneId === toLaneId, diff --git a/test/index.js b/test/index.js index d71e986..38ae814 100644 --- a/test/index.js +++ b/test/index.js @@ -28,4 +28,43 @@ const model = compiler.nativeRoad.compileRoadModel(fs.readFileSync(fixture, 'utf overrides: [], }); assert.equal(model.roads.length, 24); +// --- lane maneuver override --------------------------------------------------- +// +// The arrow a lane shows comes from the OSM `turn:lanes` tag, so overriding it is +// a v1 override like `laneCount`, not a v2 positional constraint: "which arrow" +// has no station to anchor to. +{ + const { validateOverrides } = require('../src/compile/native-road'); + const laneModel = { + roads: [{ id: 'road:way/1:forward', sourceRoadId: 'way/1', segmentId: 'segment:way/1/0', laneCount: 2 }], + endpoints: [], + connections: [], + }; + const wrap = (item) => ({ schema: 'native-road-overrides/v1', overrides: [item] }); + const maneuver = (value, laneId = 'lane:road:way/1:forward:1') => ({ + id: 'm', + kind: 'lane-maneuver', + laneId, + maneuver: value, + }); + + assert.doesNotThrow(() => validateOverrides(wrap(maneuver('through;left')), laneModel)); + // '' is not "no override": it removes an arrow the tag asked for. + assert.doesNotThrow(() => validateOverrides(wrap(maneuver('')), laneModel)); + assert.throws(() => validateOverrides(wrap(maneuver('u-turn')), laneModel), /Invalid lane maneuver/); + // normalizeManeuver() returns unknown input unchanged, so the override layer is + // the only thing standing between a typo and a silently missing arrow. + assert.throws(() => validateOverrides(wrap(maneuver('left;through')), laneModel), /Invalid lane maneuver/); + assert.throws(() => validateOverrides(wrap(maneuver(3)), laneModel), /Invalid lane maneuver/); + assert.throws( + () => validateOverrides(wrap(maneuver('left', 'lane:road:way/1:forward:9')), laneModel), + /Unknown lane maneuver override target/, + ); + // An unknown target retires like any other stale override rather than throwing. + const stale = validateOverrides(wrap(maneuver('left', 'lane:road:way/9:forward:1')), laneModel, { + skipStaleTargets: true, + }); + assert.equal(stale.stale.length, 1); +} + console.log('road compiler package tests passed');