Files
road-compiler/.trellis/tasks/08-28-crosswalk-element-editor/design.md
T
que01andClaude Opus 5 623481fd2c chore(task): correct the elementId premise and split the first gate
Measured rather than assumed: grouping the 48 stripes by crossing_node_id yields
exactly 8 groups of 6, and no crossing maps to more than one road. The uniqueness
is structural — compileControlMarkings() iterates model.crossings and each pass
emits one group from one candidate — so crosswalk:node/<crossingId> is already a
stable group id and needs no compiler change.

The earlier claim that no group id existed conflated the crossing node
(node/-26452, the pedestrian crossing) with the junction node (node/1140799725).
Different ids. Grouping client-side therefore reads a published identifier rather
than clustering by proximity, which is what the PRD forbids.

The missing affects entries are real and unchanged, but they only degrade
drag highlighting; they do not block selection. The two are now separate steps,
and selection moves first because it costs nothing on the server.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 13:13:09 +08:00

7.5 KiB
Raw Blame History

斑马线元素级编辑器设计

架构边界

本实验扩展现有直接编辑链路,而非建立画布对象存储:

crosswalk feature 点击
  -> elementId
  -> element manifest (anchor + parameters + legal controls)
  -> native-road-edits/v2 constraint
  -> resolveDirectEditConstraints
  -> compileControlMarkings
  -> preview / save / recompile

elementId 是选择和分组标识;持久化仍使用稳定语义 anchor 上的 constraint。它不能是 GeoJSON 数组下标、屏幕坐标或临时 UUID。

选择合同

斑马线的每一条 stripe feature 必须包含 native_id、element_id 与可回链的 crossing / approach 身份。选择适配层只读取 element_id,再向服务器取得选中元素的权威 manifest。客户端不会据条带数量、空间距离或渲染顺序自行聚类。

元素 manifest 至少包含:

interface EditableElement {
  elementId: string
  kind: 'crosswalk'
  anchor: { type: 'junction-approach'; nodeId: string; segmentId: string }
  featureIds: string[]
  controls: Array<{
    kind: 'position' | 'length' | 'width'
    value: { current: number; min: number; max: number; unit: 'meter' }
    axisAzimuth?: number
  }>
  fields: Array<{ key: string; value: number; min: number; max: number; unit: 'meter' | 'count' }>
}

第一阶段发布 position 与 length / width:位置沿用现有 junction-crosswalk-inset,尺寸需要新的回写规则(见「尺寸的语义」)。rotation 不在本任务范围,理由见文末。

elementId 已经存在

实测:48 条条带按 crossing_node_id 分组恰好得到 8 组、每组 6 条,且没有任何 crossing 对应多条道路。唯一性是结构性的——compileControlMarkings() 的循环是 for (const crossing of model.crossings),每次迭代由单个 crosswalkCandidate 产出一组。

因此 crosswalk:node/<crossingId> 就是稳定的组标识,无需新增编译器字段。 条带 native_id 形如 crosswalk:node/-26452:1,组前缀直接可用; crossing_node_id 也已在 feature 属性里。

客户端据此分组不构成 PRD 禁止的「按经纬度近似聚类」——它读的是已发布的稳定 标识,不是空间猜测。

早期分析曾断言组标识缺失,理由是「同一节点的多个进口共用它」。那是把 crossing 节点(node/-26452,人行横道)与 junction 节点 (node/1140799725,路口)混为一谈了。两者不是同一个 id。

affects 缺失仍是真问题

上一节不影响这一节。junctionAffects()(direct-edit-solver.js:628)构造的是 junctionSurfaceId + roadAffects + connectors,从不加入 crosswalk 或 stop-line。 实测在有 48 条斑马线的区域,junction-crosswalk-inset 手柄的 affects 共 59 项, crosswalk 为 0。

成因是求解器手上没有「进口 → crossing」的映射:该关系在编译器的 compileControlMarkings() 内部由 arrivalEndpointIds 与距离阈值算出,从未对外发布。

后果限于拖拽高亮会亮错一片(PRD 第 2 条要求高亮受影响对象)。 它不阻塞选中,因为选中走的是上一节的组标识。两者是独立的两步。

编辑与预览

  • 选择由 MapCanvas 的 feature 事件产生,但选择状态由 App/编辑会话持有,不能写入 baseline source。
  • 元素控件写入的是 manifest 指定的 constraint kind/value;表单复用同一写入器。
  • 选中框和控件只是 editHandles / editGhost 层的临时 UI;权威预览仍由服务端返回,baseline source 不被客户端改写。
  • 空白点击会清除元素选择;道路选择可继续决定道路级 handle manifest。斑马线元素选中与道路选择可并存,但两组控件不得重叠或竞争同一 pointer 手势。

尺寸的语义

斑马线的几何目前全是字面量(native-road.js:1264):

rectangleAt(controlCenter, axis, across, 3, 0.45, -2.25 + index * 0.9)
//                                       ↑长   ↑宽    ↑偏移,共 6 条

rectangleAt(center, axis, across, length, width, offset) 中 length 沿 axis (行车方向),width 沿 across(横跨道路)。所以:

用户看到的 实际是什么 存储形态
进深(沿行车方向) 每条条带的 length,6 条共用 一个数,可直接参数化
跨度(横跨道路) 条带数 × 间距,非存储值 派生量

跨度是派生量,所以拖四角改跨度必须决定改哪个因子。已定:固定间距、改条带数。

  • 条带宽 0.45m 与间隙 0.45m(间距 0.9m)在现实中是标准化的,改间距会让宽路上的 斑马线拉得很稀,不符合任何规范。
  • 代价是跨度手柄按 0.9m 量化跳动,不是连续的。这是语义诚实的结果, 不是手感缺陷;UI 上必须让它看起来是有意吸附的。

同时修掉一个既有缺陷:跨度恒为 5.4m,与路宽无关。20m 宽的路上斑马线也只有 5.4m,横不过去。参数化后默认跨度应由路宽推导,而不是写死 6 条。

选中框与抓手

视觉采用常规 transform gizmo:矩形虚线选框 + 四角空心方块。

一条硬规矩:画几个抓手,就得有几个是活的。 画了拖不动的四角、或转了没反应的 旋转柄,正是 flag.ts 为 profile.interval 立下的反面教材—— 「一个拖了没效果的控件比没有控件更糟」。长得像 Figma 但只有一半能用, 比朴素的圆点更糟,用户会当成 bug 报。

所以抓手随能力分批出现,而不是先画全再逐个点亮:

抓手 语义 何时出现
虚线选框 纯反馈,无语义 第一阶段
移动 junction-crosswalk-inset 第一阶段(语义现成)
四角方块 进深 / 跨度 第一阶段(需编译器参数化)
旋转柄 相对进口轴的偏转角 不做

旋转为何押后

axis 派生自 crosswalkCandidate.placement.axis,即进口方向。要能旋转, 需要新增一个「相对进口轴的偏转角」constraint kind。而 design.md 的规矩是 新增 kind 的前提是几何阶段必须已经消费它——先证明 compileGeometry() 读取 该参数,再画任何手柄。

偏转角本身是合理的(现实中斑马线确实会相对进口斜置),且用「相对派生轴的角度」 表达是语义化的,不违反「不持久化 transform 矩阵」。但它是独立的一轮 编译器 + kind + 客户端工作,已明确押后。

数据演进

位置继续使用已有 junction-crosswalk-inset。尺寸需要新的持久化形态,本阶段一并落地:进深与条带数各是一个参数,跨度由 条带数 × 间距 派生,间距本阶段不可编辑。具体是新增专属 kind 还是扩展同一 kind 的严格 schema,在第一个门禁(进口↔组映射)通过后定,不预先固化。

新增任何 kind 前必须先证明 compileGeometry() 读它——本项目已经为 profile.interval 交付过一个拖了无效果的手柄。

缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。

兼容与回滚

  • 无新 constraint 时,编译输出与当前版本一致。
  • directEdit 关闭时不请求 element manifest、不安装元素选择交互、不产生额外图层。
  • 第一阶段每个步骤独立提交;回滚元素 UI 或 manifest 不影响既有道路级控制。