diff --git a/.trellis/tasks/08-28-crosswalk-element-editor/design.md b/.trellis/tasks/08-28-crosswalk-element-editor/design.md index 5df75a3..b1e7055 100644 --- a/.trellis/tasks/08-28-crosswalk-element-editor/design.md +++ b/.trellis/tasks/08-28-crosswalk-element-editor/design.md @@ -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/:<序号>`, +而求解器手上没有「进口 → 斑马线组」的映射。那个关系只存在于编译器的 +`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,不在客户端静默钳制真实约束。 diff --git a/.trellis/tasks/08-28-crosswalk-element-editor/implement.jsonl b/.trellis/tasks/08-28-crosswalk-element-editor/implement.jsonl index a2120a5..9f277a3 100644 --- a/.trellis/tasks/08-28-crosswalk-element-editor/implement.jsonl +++ b/.trellis/tasks/08-28-crosswalk-element-editor/implement.jsonl @@ -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":"参数表单那一半的既有实现与三个通道无关出口的契约。"} diff --git a/.trellis/tasks/08-28-crosswalk-element-editor/implement.md b/.trellis/tasks/08-28-crosswalk-element-editor/implement.md index ccb08e0..d874d92 100644 --- a/.trellis/tasks/08-28-crosswalk-element-editor/implement.md +++ b/.trellis/tasks/08-28-crosswalk-element-editor/implement.md @@ -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 基线,需显式更新而非静默接受。