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');