Files
road-compiler/.trellis/tasks/08-28-crosswalk-element-editor/implement.md
T
que01andClaude Opus 5 15d41be444 chore(task): record progress and the blocker on corner grips
Steps 1, 2 and 4 are done and step 3 is parked with a reason: the client never
reads affects and no highlighting exists, so fixing it alone changes nothing a
user can see. It belongs with the highlight, as one piece of work.

Step 5 has a design question that should be settled before code. The size value
is a pair while the drag path is scalar end to end, so a corner grip moving one
component has to preserve the other or every drag resets the half it did not
touch. Three options noted, with the reason the tempting one — letting element
controls build their own value — is the wrong shape.

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

135 lines
7.3 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` | ⏸ 暂缓——客户端从不读 `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`,
所以参数面板不渲染它——它的值是一对数,而面板渲染标量。接入抓手时一并处理。