Files
road-compiler/.trellis/tasks/08-28-crosswalk-element-editor/implement.md
T
que01andClaude Opus 5 323ff9279f docs: map which markings the element model reaches
Measured the grouping of every marking layer. Stop lines are nearly free — same
feature builder, same key shape, an existing constraint kind, and a sweep shows
the offset tracks one-to-one across its whole range with no dead zone. Arrows
are not: neither kind exists and neither is read by the geometry stage.

The trap is that crosswalks and stop lines share crossing_node_id on all eight
groups, so grouping has to branch on provenance before touching the key or the
two merge into one element. That is already how element.ts works and a test
holds it.

What the data earns is a provenance-keyed registry and nothing more: group keys
are single-field, two-field and derived; group sizes run 1 to 230; two element
types have no constraint at all. A universal element protocol would be inventing
past the evidence, which the PRD rules out.

Also records delivery state — steps 1 and 2 done, 3 through 5 not started — so
the task is not mistaken for complete.

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

6.0 KiB
Raw Blame History

实施计划

顺序按风险递减排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。

数据前提: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 且编译器先消费它,已决定押后。
  • 条带间距编辑。
  • 推广到停止线、箭头、信号灯。

验证命令

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 ⬜ 未开始
4 编译器尺寸参数化 ⬜ 未开始
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)。

手测确认:选中、虚线框、拖拽均可用。尚未手测:框跟随修复后的表现、 上界修复后的拖拽手感——两者都需重启工作台进程才能生效。