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

149 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 斑马线元素级编辑器设计
## 架构边界
本实验扩展现有直接编辑链路,而非建立画布对象存储:
```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/<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`):
```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 不影响既有道路级控制。