# 斑马线元素级编辑器设计 ## 架构边界 本实验扩展现有直接编辑链路,而非建立画布对象存储: ```text 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 至少包含: ```ts 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/` 就是稳定的组标识**,无需新增编译器字段。 条带 `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`): ```js 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 不影响既有道路级控制。