chore(task): re-plan the crosswalk experiment around one root cause

Three symptoms turned out to be one hole. junctionAffects() builds
junctionSurface + roadAffects + connectors and never adds crosswalks, so on an
area with 48 of them the crosswalk-inset handle reports 59 affected features and
zero crosswalks. The cause is that stripe ids key off the crossing node while the
solver has no approach-to-group mapping — which is also why there is no stable
elementId and why clicking a stripe cannot select the group. Publishing that
mapping resolves all three, so it is now the first gate rather than three
separate steps.

Corner resize moves into the first phase by decision; rotation is deferred, since
it needs a new constraint kind and the compiler has to consume it before any grip
may be drawn.

Sizing semantics are settled: stripe depth is a stored number, but span is
count x pitch, so the corner drag varies the count at a fixed 0.9m pitch and
therefore quantises. That is honest rather than janky and the UI has to read as
deliberate snapping. It also fixes span being pinned at 5.4m regardless of road
width, which will move fixture baselines.

Records the data prerequisite: crossing nodes are required, and the current
import had none, which is what made the handle look broken.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
que01andClaude Opus 5 committed 2026-08-31 13:02:46 +08:00
1 parent 2ef24539f9
commit 086939be93
3 files changed
+147 -26

No files matched your search

@@ -37,7 +37,28 @@ interface EditableElement {
}
```
第一阶段只发布 `position` 及其现有 `junction-crosswalk-inset` 回写规则。第二阶段再加入尺寸和条带参数,避免在实验开始前规定尚未验证的通用元素协议。
第一阶段发布 `position` 与 `length` / `width`:位置沿用现有 `junction-crosswalk-inset`,尺寸需要新的回写规则(见「尺寸的语义」)。`rotation` **不在本任务范围**,理由见文末。
## `affects` 与 `elementId` 是同一个洞
`junctionAffects()`(`direct-edit-solver.js:628`)构造的是
`junctionSurfaceId + roadAffects + connectors`,**从不加入 crosswalk 或 stop-line**。
实测在有 48 条斑马线的区域,`junction-crosswalk-inset` 手柄的 `affects` 共 59 项,
其中 crosswalk **为 0**。
成因是同一个:斑马线 feature id 用的是 `crosswalk:node/<crossing 节点>:<序号>`,
而求解器手上没有「进口 → 斑马线组」的映射。那个关系只存在于编译器的
`compileControlMarkings()` 内部,从未对外发布。
因此下面三件事是一次工作,不是三次:
| 症状 | 需要的东西 |
| --- | --- |
| `affects` 不含斑马线,拖拽高亮会亮错 | 进口 ↔ 斑马线组映射 |
| 没有稳定 `elementId` | 同上 |
| 点条带无法选中整组 | 同上 |
补上映射并随 manifest 发布,三者一起解决。这也是第一阶段的第一个门禁。
## 编辑与预览
@@ -46,9 +67,67 @@ interface EditableElement {
- 选中框和控件只是 `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 + 客户端工作,已明确押后。
## 数据演进
第一阶段不新增 persisted schema:位置继续使用已有 `junction-crosswalk-inset`。第二阶段如果确实需要尺寸参数,新增一个专属 kind 或扩展同一 kind 的严格 schema 校验;具体选择以第一阶段运行结果为准,不预先固化。
位置继续使用已有 `junction-crosswalk-inset`。尺寸需要新的持久化形态,本阶段一并落地:进深与条带数各是一个参数,跨度由 `条带数 × 间距` 派生,间距本阶段不可编辑。具体是新增专属 kind 还是扩展同一 kind 的严格 schema,在第一个门禁(进口↔组映射)通过后定,不预先固化。
新增任何 kind 前必须先证明 `compileGeometry()` 读它——本项目已经为 `profile.interval` 交付过一个拖了无效果的手柄。
缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。
@@ -1,4 +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 图层所有权。"}
{"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/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同。"}
{"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":"参数表单那一半的既有实现与三个通道无关出口的契约。"}
@@ -1,35 +1,73 @@
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
数据前提:`nantaizihu-9PTsZg`(由桌面 `南台子湖创新谷OSM.osm` 导入)含 10 个
`highway=crossing` 节点、8 组 zebra,编译出 48 条斑马线与 8 条停止线。
不带 crossing 的 OSM 无法验证本任务任何一步。
## 0. 建立事实与测试夹具
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成和从地图点击到 `onFeature` 的路径。
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线一致。
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成,以及从地图点击到 `onFeature` 的路径。
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线字节一致。
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
## 1. 第一阶段:元素 manifest 与选择
## 1. 进口 ↔ 斑马线组映射(第一门禁)
- 在编译器为 crosswalk stripe 写稳定的元素标识和回链属性。
- 在 direct-edit 服务响应中增量发布按 selection/element 获取的元素 manifest,不扩大现有道路 handle 的职责。
- 客户端建立 `ElementSelection` 纯状态与 feature 点击适配;点击 stripe 选择整组、空白清除。
- 验证:编译器单元测试、API 测试、客户端 selection 单元测试。
`design.md` 已论证 `affects` 不含斑马线、缺少 `elementId`、无法整组选中是**同一个洞**:
求解器没有「进口 → 斑马线组」的映射,该关系只存在于编译器内部。
## 2. 第一阶段:位置编辑闭环
- 编译器为每组斑马线写稳定的组标识与回链属性,随 stripe feature 发布。
- 求解器建立并消费该映射,使 `junctionAffects()` 不再遗漏 crosswalk。
- 在 direct-edit 响应中增量发布按 selection/element 获取的元素 manifest,不扩大现有道路 handle 的职责。
- 验证:编译器单测(同组共享、跨组不共享、重编译后稳定)、API 测试。
- **门禁**:`junction-crosswalk-inset` 手柄的 `affects` 必须包含它实际移动的那 6 条 crosswalk feature。当前实测为 0,这是本步是否成立的判据。失败即停——后面每一步都依赖这个映射。
- 用 element manifest 的 position control 渲染元素级控件和选中外框;安装时不得影响道路 handle hit-test。
- 从位置手势和表单走同一个 draft builder,写入 `junction-crosswalk-inset`。
- 验证:拖拽与表单值生成同形约束;预览/保存/重载一致;`exact` 状态和撤销/重做覆盖。
- 门禁:一次非空编辑可在正式重编译结果中观察到斑马线位置变化。失败即停止,不能只交付 UI。
## 2. 元素选择
## 3. 复盘门禁
- 客户端建立 `ElementSelection` 纯状态与 feature 点击适配;点击任一条带选中整组、点空白清除。
- 选择状态由 App / 编辑会话持有,不写入 baseline source。
- 元素选中与道路选择可并存,但两组控件不得竞争同一 pointer 手势。
- 验证:客户端 selection 单元测试;手测切换、取消、与道路级手柄共存。
- 手测选中、取消、道路级手柄共存、拖拽钳位、表单验证、保存重载。
- 只有在第一阶段验收全部通过后,才能为尺寸/外观参数做持久化 schema 决策。
## 3. 选中框与移动
## 4. 第二阶段:尺寸与外观
- 渲染矩形虚线选框(框住整组 6 条)+ 移动抓手,接已有 `junction-crosswalk-inset`。
- 控件走 `App.tsx` 既有的三个出口 `draftValue()` / `settleValue()` / `abandonGesture()`,**不新建第二条预览或 undo 链路**(见 `.trellis/spec/frontend/direct-edit-client.md` §11)。
- 安装时不得影响道路 handle 的 hit-test。
- **门禁**:一次非空元素编辑可在正式重编译结果中观察到斑马线位置变化。只交付 UI 不算通过。
- 依据第一阶段证据设计并验证长度、宽度、条带数、间距的约束 schema。
- 编译器读取参数、返回 blocking diagnostics;元素 manifest 表达对应控件/字段。
- 实现与表单字段完全一致的尺寸控件,补齐组合参数、持久化和 rebase 测试。
## 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 且编译器先消费它,已决定押后。
- 条带间距编辑。
- 推广到停止线、箭头、信号灯。
## 验证命令
@@ -43,7 +81,9 @@ npm run build
## 风险文件
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性。
- `src/compile/direct-edit-solver.js` / `native-road-edits.js`:约束求解、schema 和 manifest 必须同步。
- `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/components/MapCanvas.tsx`、`App.tsx`、`edit/`:选择、临时控件和表单不得污染 baseline layer。
- `workbench/client/src/App.tsx`、`edit/`、`components/`:元素控件必须接既有三出口;选中框是临时 UI,不得写 baseline layer。
- `test/fixtures.js`:默认跨度改由路宽推导会改动 fixture 基线,需显式更新而非静默接受。