chore(task): archive completed road editor workflows

This commit is contained in:
que01 committed 2026-09-07 14:21:57 +08:00
1 parent 39e338668b
commit d61c86ed2c
26 files changed
+6 -6

No files matched your search

@@ -0,0 +1,3 @@
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"检查 preview 零写入、非空约束改变正式编译输出、保存与 rebase 合同。"}
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"检查 baseline 不被元素编辑代码写入、控件由 manifest 驱动且预览时序正确。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"核对 feature -> element -> manifest -> constraint 的完整读写链路。"}
@@ -0,0 +1,148 @@
# 斑马线元素级编辑器设计
## 架构边界
本实验扩展现有直接编辑链路,而非建立画布对象存储:
```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 不影响既有道路级控制。
@@ -0,0 +1,6 @@
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"元素 manifest、preview 和持久化必须继续满足直接编辑的服务端合同。"}
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"元素选择、临时控件与表单必须保持 handle/ghost/preview 图层所有权;§11-14 定义了输入通道汇合点、夹值/拒绝分工与聚焦期文本所有权。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"feature 属性、element manifest、constraint schema 与客户端选择状态跨越编译器、API 和 UI。"}
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"元素控件必须接既有 draftValue/settleValue/abandonGesture,禁止新建第二条预览或 undo 链路。"}
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同,以及新增 kind 前必须先证明几何阶段消费它的规矩。"}
{"file":".trellis/tasks/08-31-parameter-panel-binding/design.md","reason":"参数表单那一半的既有实现与三个通道无关出口的契约。"}
@@ -0,0 +1,134 @@
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
数据前提:`nantaizihu-9PTsZg`(由桌面 `南台子湖创新谷OSM.osm` 导入)含 10 个
`highway=crossing` 节点、8 组 zebra,编译出 48 条斑马线与 8 条停止线。
不带 crossing 的 OSM 无法验证本任务任何一步。
## 0. 建立事实与测试夹具
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成,以及从地图点击到 `onFeature` 的路径。
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线字节一致。
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
## 1. 元素选择(纯客户端)
`design.md` 已实测确认 `crosswalk:node/<crossingId>` 就是稳定组标识,
条带属性里已有 `crossing_node_id`。**本步不需要改编译器。**
- 客户端建立 `ElementSelection` 纯状态:从 feature 属性推出组标识,不做空间聚类。
- 点击任一条带选中整组、点空白清除;选择状态由 App / 编辑会话持有,不写 baseline source。
- 元素选中与道路选择可并存,但两组控件不得竞争同一 pointer 手势。
- 验证:客户端 selection 单元测试(同组共享、跨组不共享、重编译后稳定)。
- **门禁**:一个具体 feature 无歧义回链到一个组,且组内条带数与编译输出一致。
## 2. 选中框与移动
- 渲染矩形虚线选框(框住整组 6 条)+ 移动抓手,接已有 `junction-crosswalk-inset`。
- 控件走 `App.tsx` 既有的三个出口 `draftValue()` / `settleValue()` / `abandonGesture()`,**不新建第二条预览或 undo 链路**(见 `.trellis/spec/frontend/direct-edit-client.md` §11)。
- 安装时不得影响道路 handle 的 hit-test。
- **门禁**:一次非空元素编辑可在正式重编译结果中观察到斑马线位置变化。只交付 UI 不算通过。
## 3. 修正 `affects`(服务端)
独立于第 1 步——选中不依赖它,但拖拽高亮依赖。
- 求解器建立并消费「进口 → crossing」映射,使 `junctionAffects()` 不再遗漏 crosswalk。
该关系目前只存在于 `compileControlMarkings()` 内部(`arrivalEndpointIds` + 距离阈值)。
- 验证:API 测试。
- **门禁**:`junction-crosswalk-inset` 手柄的 `affects` 必须包含它实际移动的那 6 条 crosswalk feature。当前实测为 0。
## 4. 编译器尺寸参数化
斑马线几何目前全是字面量(`native-road.js:1264`:长 3m、宽 0.45m、间距 0.9m、6 条)。
- 进深与条带数成为参数;间距本阶段固定 0.9m 不可编辑;跨度 = 条带数 × 间距,派生。
- 默认跨度由路宽推导,修掉「跨度恒为 5.4m 与路宽无关」的既有缺陷。
- 无约束时输出与当前版本**字节级一致**(除上述默认跨度修正外,该修正需单独记录并更新基线)。
- 越界、条带重叠、超出可用进口范围返回 blocking diagnostic。
- **门禁**:先证明 `compileGeometry()` 读取新参数,再画任何抓手。这条规矩来自
`profile.interval` 那次教训——求解器写了、几何阶段没读、交付了一个拖动无效果的手柄。
## 5. 四角尺寸抓手
- 四角空心方块:一轴改进深(连续),一轴改跨度(按 0.9m 量化吸附)。
- 量化必须看起来是有意吸附,不能像卡顿。
- 表单与抓手写同一组元素参数,值、单位、范围、诊断一致。
- **门禁**:画出来的每个抓手都必须是活的。宁可少画,不可画死的
(`direct-edit-client.md` 的 `intervalEditingSupported` 先例)。
## 6. 复盘
- 手测:选中、取消、道路级手柄共存、移动钳位、尺寸吸附、表单校验、保存重载、撤销/重做。
- 记录哪些结论可推广到停止线/箭头,哪些**不可**——斑马线只改位置与自身尺寸,
不改路口形状;`approach-width` / `cutback` / `corner-radius` 是另一个几何类别,
本实验不为它们背书(见 `prd.md` 的「试验对象的覆盖边界」)。
## 明确不做
- 旋转。需要新增「相对进口轴偏转角」constraint kind 且编译器先消费它,已决定押后。
- 条带间距编辑。
- 推广到停止线、箭头、信号灯。
## 验证命令
```sh
npm run format:check
npm run test
npm run test:client
npm run test:client:unit
npm run build
```
## 风险文件
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性;尺寸参数化会动到基线快照。
- `src/compile/direct-edit-solver.js`:`junctionAffects()` 是第 1 步的核心;element manifest 与 handle manifest 不得互相污染。
- `src/compile/native-road-edits.js`:新增 kind 或扩展 schema 时校验必须同步。
- `workbench/server.js`:element manifest 查询与 preview 不得写入磁盘。
- `workbench/client/src/App.tsx`、`edit/`、`components/`:元素控件必须接既有三出口;选中框是临时 UI,不得写 baseline layer。
- `test/fixtures.js`:默认跨度改由路宽推导会改动 fixture 基线,需显式更新而非静默接受。
---
## 交付进度(2026-08-31)
| 步骤 | 状态 |
| --- | --- |
| 0 建立事实与测试夹具 | ✅ |
| 1 元素选择 | ✅ `edit/element.ts`,浏览器已确认;已推广到停止线 |
| 2 选中框与移动 | ✅ 虚线框可直接拖拽 |
| 3 修正 `affects` | ⏸ 暂缓——客户端从不读 `affects`,高亮未实现,单独修不可见。应与高亮作为一件事做 |
| 4 编译器尺寸参数化 | ✅ `junction-crosswalk-size`,门禁已过,基线已更新 |
| 5 四角尺寸抓手 | ⬜ 未开始,见下方设计难点 |
| 6 复盘 | 部分:推广分析见 `research/generalising-to-other-markings.md` |
第 1–2 步之外另修了两处既有缺陷:`MapCanvas` 的陈旧闭包与空白点击不上报,
以及 `junction-crosswalk-inset` 的上界(44%~88% 死区,见
`08-31-parameter-panel-binding/research/manifest-range-vs-solver.md`)。
手测确认:选中、虚线框、拖拽均可用。**尚未手测**:框跟随修复后的表现、
上界修复后的拖拽手感——两者都需重启工作台进程才能生效。
## 第 5 步的设计难点(未解决)
`junction-crosswalk-size` 的值是**一对数** `{ depthMeters, stripeCount }`,
而拖拽链路是标量的:`projectHandleValue` 产出一个数,`constraintValueFor`
把它包成一个 value。四角抓手需要两个自由度:
- 一轴改进深(连续,米)
- 一轴改跨度(量化,写回 `stripeCount`)
拖其中一个必须**保留另一个的当前值**,否则每次拖拽都会把未触碰的那半重置为默认。
可行方向(未定):
1. 发两个标量手柄,`draftFor` 在构造 value 时与已有约束合并
2. 扩展 `EditHandle` 表达多分量,改动面更大
3. 元素控件不走 `draftFor`,自己构造 value——**违反「两条通道汇合于同一出口」**,不推荐
方向 1 最小,但需要 `draftFor` 能读到该约束的当前值;目前它只从 handle 拿标量。
动手前应先定这个,否则会长出第二条 draft 路径。
另:`junction-crosswalk-size` 已加入 `JUNCTION_KINDS` 但**不在** `CONTROL_KINDS`,
所以参数面板不渲染它——它的值是一对数,而面板渲染标量。接入抓手时一并处理。
@@ -0,0 +1,83 @@
# 斑马线元素级编辑器实验
## 目标
验证“元素级编辑器”能取代只显示固定道路参数手柄的交互:用户点击一组斑马线的任一条带后,整组进入选中状态,地图显示该元素的编辑控件,参数表单与地图操作都能预览、保存和撤销同一份结构化编辑。
斑马线是实验对象,实验通过后才抽象和推广到停止线、箭头、信号灯等元素。
## 已确认的事实
- 当前 `junction-crosswalk-inset` 只改变斑马线相对路口的位置;控制手柄属于被选道路的进口,而非具体斑马线。
- `compileControlMarkings()` 为一组斑马线生成多条 `crosswalk` GeoJSON feature;每条 feature 的属性目前不足以作为稳定的组级编辑目标。
- 浏览器已有 `EditSession`、服务端权威 preview、保存、重编译与撤销链路。编辑数据必须保持语义约束,不得保存派生 GeoJSON 或屏幕坐标。
- 当前普通道路级手柄仍服务于横断面参数,不应与元素级选择共用或互相覆盖。
- `08-31-parameter-panel-binding` 已交付参数表单那一半:`ParameterPanel` 组件、`edit/parameter.ts` 的文本↔数值/范围判定/单位换算,以及 `App.tsx` 中通道无关的三个出口 `draftValue()`(预览)、`settleValue()`(提交一步 undo)、`abandonGesture()`(放弃)。元素级控件应接入同一组出口,**不要新建第二条预览或 undo 链路**。
## 范围
### 第一阶段:元素选择与位置闭环
1. 点击任意一条斑马线条带,选中整组斑马线;点击空白处或另一道路元素清除或切换选择。
2. 后端为每组斑马线发布稳定 `elementId`、元素类型、语义锚点、可编辑参数与受影响 feature ID;客户端不得由 feature 数组位置猜测分组。
3. 选中后显示轻量的元素级编辑状态,至少有位置控制;移动只允许沿该进口定义的合法轴和范围,钳位来自服务端 manifest。
4. 位置控制和参数表单共同更新既有 `junction-crosswalk-inset` 约束,并复用 preview、保存、撤销与重编译链路。
5. 表单显示当前值、单位、合法范围和阻塞性诊断;修改后更新地图预览,保存后重新编译仍为 `exact`。
### 第二阶段:尺寸与外观闭环(本任务内设计、第一阶段通过后实施)
1. 选中框提供与斑马线语义相符的长度/宽度调整,不写自由像素缩放。
2. 表单可修改斑马线长度、宽度、条带数量和条带间距;地图控件与表单写同一结构化元素参数。
3. 编译器消费这些参数生成整组条带,并对不合法组合返回阻塞诊断。
## 明确不做
- 不实现通用的任意旋转、自由二维移动、任意缩放或把 transform 矩阵持久化。
- 不编辑多组斑马线,不跨进口/跨路口拖放,不改变 OSM 中心线或路口拓扑。
- 不在本任务中推广停止线、箭头或信号灯;不提前建立“所有元素”的大而全抽象。
- 不移除或改变道路横断面、路口 shape 的现有手柄和所有权。
## 验收标准
- [ ] 点击一条条带后,整组条带显示为同一选中元素;切换到另一组或空白处时状态正确更新。
- [ ] `elementId` 在同一输入、重编译、保存和重新加载后稳定;同组条带共享一个 ID,不同斑马线不共享。
- [ ] 移动控件与表单修改位置时,预览只更新该元素及其声明的受影响层;无效输入保留最后一个有效预览并显示诊断。
- [ ] 保存、刷新、重新编译后位置不回退,相关约束状态为 `exact`;未保存编辑可以撤销/重做。
- [ ] 第二阶段完成后,长度/宽度/条带数量/间距能从表单和地图控件一致地更新,非法尺寸或间距被拒绝而非静默修复。
- [ ] 现有道路级手柄仍可独立工作,且未选中斑马线时不显示元素编辑 UI。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 通过。
## 风险与门槛
- 第一阶段必须先证明 feature -> element -> semantic anchor 的稳定回链,以及非空约束确实改变正式编译输出;两者任一失败时停止,不进入尺寸和外观参数。
- 选中框是交互反馈,不能成为第二个几何模型;所有位置、范围和尺寸的权威值由后端 element manifest 给出。
- 当前地图 feature 的属性可能缺少足以识别 crossing 的稳定字段。需要先通过编译器补充,不可在客户端按经纬度近似聚类。
### 试验对象的覆盖边界(2026-08-31 决定)
本任务的上游动机是**为复杂路口做前置**:普通四岔口已有 20 个手柄分属 4 条 segment,
主地图一次只显示当前选中 segment 的手柄,要看全一个路口需依次选中 4 条道路。
每参数一个圆点的模型撑不到复杂路口,元素级选中是必需品而非优化。
已明确决定:**第一次试验只做斑马线,不并入形状类元素**,以控制风险。
代价必须记录在案——斑马线是**位置类**元素,`design.md` 明确「不改变路口形状,
只移动标线,因此不触发路口边界重算」。而复杂路口真正难的是
`junction-approach-width` / `junction-cutback` / `junction-corner-radius`:
它们改变路口多边形本身,涉及边界连续、面自交、cutback 处截面衔接。
因此:
- 本试验通过 **只证明**「选中 + 位置编辑」这条链路可行。
- 它 **不证明** 形状类元素的元素级编辑可行,那是另一个几何类别。
- 推广到形状类元素前必须单独验证,不得以本试验的结论替代。
## Acceptance Criteria
- [ ] TBD
## Notes
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
- Lightweight tasks can remain PRD-only.
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
@@ -0,0 +1,84 @@
# 元素模型能推广到哪些标线
日期:2026-08-31
来源:`08-28-crosswalk-element-editor` 第 1–2 步交付后,对 `nantaizihu-9PTsZg` 的实测。
## 各元素的分组结构(实测)
| 图层 | provenance | 分组键 | feature | 组数 | 每组大小 |
| --- | --- | --- | --- | --- | --- |
| `crosswalks` | `native-road-crosswalk/v1` | `crossing_node_id` | 48 | 8 | 恒 6 |
| `vehicleStopLines` | `native-road-stop-line/v1` | `crossing_node_id` | 8 | 8 | 恒 1 |
| `turnArrows` | `native-road-turn-arrow/v1` | `lane_id` + `maneuver` | 108 | 28 | 3 或 5 |
| `directionArrows` | `native-road-direction-arrow/v1` | `lane_id` | 324 | 50 | 2~28 |
| `laneSeparators` | `native-road-lane-separator/v1` | `road_id` + 车道对 | 731 | 9 | 26~230 |
## 关键陷阱:斑马线与停止线共用 `crossing_node_id`
交集 **8/8**——两者由同一个 `controlFeature()` 构造,`crossing_node_id` 完全重合。
只按该字段分组会把一组斑马线和它的停止线并成一个"元素"。
**必须先按 `provenance` 判类型,再取分组键。** `element.ts` 已如此实现并有测试守着
(`rejects a stop line, which shares the same feature builder`)。任何推广都不能绕过这一步。
## 可编辑性就绪度
| 元素 | 约束 kind | 编译器是否消费 | 实测响应 | 成本 |
| --- | --- | --- | --- | --- |
| 斑马线 | `junction-crosswalk-inset` | ✅ | 已修正上界,全程有效 | **已完成** |
| 停止线 | `junction-stop-line-offset` | ✅ | **全程线性,零死区** | **几乎免费** |
| 转向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
| 方向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
| 车道分隔线 | v1 overrides,仅样式 | 仅样式 | 位置不可编辑 | 另一类问题 |
停止线实测:offset `0.5 → 126` 位移 `0 → 125.36m`,增量始终 1:1。
**没有斑马线那种死区**,可以直接接入。
但它有反向的毛病:声明范围 `[0.5, 126.28]`(`approach.length * 0.45`),
允许把停止线推到离路口 126 米——而 `native-road.js` 有
`STOP_LINE_MAX_APPROACH_DISTANCE_METERS = 25`。范围过宽同样是缺陷,
见 `.trellis/spec/backend/direct-edit-api.md` §12。
## 值得建立的抽象(仅此而已)
一个按 provenance 索引的小注册表:
```ts
interface ElementSpec {
provenance: string;
kind: ElementKind;
groupKey(properties: Record<string, unknown>): string | null;
constraintKind: ConstraintKind;
}
```
`element.ts` 现有的 `crosswalkElementIdOf` / `groupMembers` / `elementSelectionFor`
改为查表即可,选中、选框、拖拽三条链路无需改动。
**不要**据此建立"所有元素"的通用协议——PRD 明确禁止
(「不提前建立『所有元素』的大而全抽象」)。理由在上表里:
分组键的形态各不相同(单字段 / 双字段 / 派生),
每组大小从 1 到 230,箭头类连约束 kind 都还不存在。
现在能证明的只有「provenance + 分组键 → 组」这一条,注册表恰好只承诺这一条。
## 推荐顺序
1. **停止线**——注册表 + 一条 spec 条目。约束现成、编译器已消费、响应已验证。
同时暴露注册表是否够用:它的每组只有 1 个 feature,而斑马线是 6 个,
能验证分组逻辑不依赖"多 part"这个偶然属性。
2. **修 `affects`**(原第 3 步)——目前 `junctionAffects()` 不含任何标线,
拖拽高亮会亮错一片。停止线接入后这个问题会更明显。
3. **转向箭头**——需要新 constraint kind,且必须先证明 `compileGeometry()` 读它。
分组键 `lane_id + maneuver` 已验证(28 组,每组 3 或 5 个 part)。
4. **方向箭头**——最贵。分组语义本身待定:按 `lane_id` 是 50 组(编辑间距/整体偏移),
按 `lane_id + sequence` 是 324 组(逐个箭头独立摆放)。
这是产品决策,不是实现细节,需先定。
5. **车道分隔线**——不同类问题。已有 v1 样式 override,缺的是位置,
而位置由 `road-lane-divider` 约束管,属道路横断面而非元素级。
## 与复杂路口的关系
停止线和转向箭头都是**位置类**元素,与斑马线同属一个几何类别:
移动它们不改变路口多边形。所以第 1、3 步不会为形状类元素
(`approach-width` / `cutback` / `corner-radius`)提供任何背书——
那仍是独立的、未验证的一类,见 `prd.md`「试验对象的覆盖边界」。
@@ -0,0 +1,26 @@
{
"id": "crosswalk-element-editor",
"name": "crosswalk-element-editor",
"title": "斑马线元素级编辑器实验",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-28",
"completedAt": "2026-09-07",
"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": {}
}