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

113 lines
6.0 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.
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
数据前提:`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` | ⬜ 未开始 |
| 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`)。
手测确认:选中、虚线框、拖拽均可用。**尚未手测**:框跟随修复后的表现、
上界修复后的拖拽手感——两者都需重启工作台进程才能生效。