Files
road-compiler/.trellis/tasks/08-31-parameter-panel-binding/prd.md
T
que01andClaude Opus 5 1c27501534 feat: edit road parameters by number as well as by drag
The map had one input device. A drag projects a pointer onto the manifest's
axis; there was no way to state a value, read one, or withdraw one.

Both channels now meet at the same three exits in App.tsx — draftValue()
previews, settleValue() commits one undoable command, abandonGesture() puts the
settled state back — so nothing about the constraint, the debounce or the
previewSeq arbitration is implemented twice. EditSession is untouched: focus and
blur land on the gesture boundary that pointerdown and pointerup already used,
which is why typing 1.53 is one undo step rather than four.

Three rules the two devices do not share:

- Live drag values bypass React and write the input's value directly, per
  direct-edit-client.md §7. A layout effect re-applies them after a mid-drag
  preview replaces the manifest, and drops the override once the manifest
  reports the value the drag asked for.
- Typed values out of range are refused, not clamped. A pointer cannot state an
  intent it never reached, so a drag clamps; typed text is an intent, and a
  clamped typo reads as a plausible value that can go unnoticed. The offered
  extremes round inward — a real max of 2.925 renders as 2.93 under
  nearest-rounding, which the range it came from would then reject.
- Reset disables the constraint rather than deleting it: validateEditDocument()
  rejects an operation naming a constraint that is not in the document. This is
  the one edit a drag cannot express, since a drag can set a value but never
  withdraw one.

Interval editing stays behind intervalEditingSupported, which is still false —
compileGeometry() does not read profile.interval, and a control that changes
nothing is worse than no control. The conversions are implemented and tested so
the row appears when the flag flips.

Probing a live manifest turned up a defect that is not from this change and is
not fixed here: an edge offset advertises ±2.925 while the solver rejects past
about ±1. Evidence is in the task's research/, and the requirement moved to
08-31-constraint-range-validation.

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

7.7 KiB
Raw Blame History

参数面板与数值双向绑定

目标

给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。

地图直接操纵保留,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。

已确认的事实

以下均为读代码核实,不是推断:

  • App.tsx:206 的 draftFor(handle, value) 已经是纯函数 (手柄, 数字) → 草稿。拖拽只是产生这个数字的一种方式;输入框可以复用同一个入口。
  • EditHandle.value 是 { current, min, max, unit: 'meter' }——取值范围服务端早已下发,客户端不需要新增来源。
  • direct-edit-solver.js:136 的 numericValue(constraint, key, fallback) 直接从约束读值,无约束时回落基线。服务端从不改写用户输入的数字;值非法时发阻塞诊断(direct-edit-invalid-value)拒绝,不做静默替换。因此不存在"请求值 vs 求解值"两个数字。
  • App.tsx:197 每次预览结算都 setManifest(response.handles) 整体替换 manifest,value.current 随之刷新。受控输入若直接绑定它,输入中间态(1.、-、空串)会被冲掉。
  • projection.ts:60 的 projectHandleValue 把拖拽值夹到 [min, max],ghost.show() 与 handlePositionFor() 都按夹后的值绘制。拖拽越界时手柄停在极限、光标继续移动。
  • 服务端 applyConstraint(direct-edit-solver.js:302/312/322 附近)只校验 Number.isFinite 与非负,未校验 manifest 的 min/max。范围目前是纯客户端概念。
  • 外缘偏移的范围随道路宽度浮动(±Math.max(0.1, width * 0.45));步行带固定 0..8;角部圆角固定 0.5..30。
  • gestureIdentity() 懒创建 operationId,commitGesture() 释放它。一次 gesture = EditSession.commit() 一次 = 一步 undo。该机制与指针无绑定关系。
  • handle.constraintId 仅在约束存在时出现,因此客户端能区分"未修改(基线回落)"与"显式设为该值"。
  • 区间由整条道路共享:rangeDraftFor 会把该路上所有约束一起重锚。IntervalRangeHandle 同时携带 station 与 roadLengthMeters。
  • 同一条路可有多个 road-lane-divider 手柄,靠 boundaryIndex 区分。
  • direct-edit-solver.js 写 profile.interval(290、472 行),但 compileGeometry() 不读它——native-road.js 中 interval 的唯一命中是方向箭头间距,与此无关。每次直接编辑实际作用于整条道路。 因此 flag.ts:46 的 intervalEditingSupported 为 false,range 手柄被隐藏。
  • 当前没有任何参数面板。与手柄相关的 UI 仅 App.tsx:404 状态栏一句 手柄 ${n} 个。
  • handleDragEvent 每次 mousemove 触发;App.tsx 是单个 974 行组件。

范围

1. 面板与读取

  1. 选中道路后,面板按手柄列出可编辑参数:中文名、当前值、单位、合法范围。
  2. 多个 road-lane-divider 分别成行,用 boundaryIndex 标识,不按 kind 去重。
  3. 影响区间每条路一行(不是每个手柄一行),以米显示,station 仍是唯一存储真相。 受 intervalEditingSupported 门控:该开关当前为 false,故本任务不渲染区间行。 换算与显示逻辑仍按第 5 节实现并单测,随开关翻转一并生效。
  4. 每行标记该参数是否已被显式修改(依据 handle.constraintId 是否存在)。
  5. 不可编辑手柄(落在路口保留区)在面板中呈禁用态并显示 disabledReason。

2. 拖拽 → 数字

  1. 拖拽过程中面板数值实时跟随,与地图 ghost 同步。
  2. 高频更新经 rAF 节流,不得每次 mousemove 触发整个 App 重渲染。

3. 数字 → 图形

  1. 输入框修改值时走与拖拽相同的 draftFor → PreviewRequester 链路,含 80ms 防抖与 previewSeq 仲裁。
  2. gesture 边界:focus 对应 pointerdown(铸 operationId),blur / Enter 对应 pointerup(commitGesture)。输入 1.53 只产生一步 undo。
  3. Escape 回滚到上一个有效值并 cancel() 在途请求。
  4. 聚焦期间输入框显示本地文本,失焦后跟随 value.current。中间态不被预览响应冲掉。
  5. saveDirectEdits() 入口先强制结算未闭合的 gesture,不依赖 blur 与 click 的触发顺序。

4. 范围处理

  1. 拖拽与滑杆维持夹值(projectHandleValue 不变)。
  2. 数值输入不夹值:越界时标记非法、不发预览、不进 undo 栈,保留最后一个有效预览。
  3. 范围提示中的极值可一键填入。

5. 重置

  1. 每行提供"重置",删除该约束回到基线。这是拖拽无法表达的操作——拖拽只能设值,不能移除约束。

明确不做

  • 不移除、不削弱地图上的拖拽手柄。
  • 不新增约束 kind,不改动求解器几何逻辑。
  • 不补服务端 min/max 校验(见「已知缺口」,另立任务)。
  • 不做参数的批量编辑、复制粘贴、跨道路应用。
  • 不动 JunctionTools 的所有权边界;面板只呈现主地图拥有的 kind。
  • 不同步遗留 workbench/client/app.js。

验收标准

  • 选中道路后面板列出全部可编辑参数;多条车道分隔各自成行且可独立修改。
  • 拖拽手柄时面板数值实时跟随;拖拽期间 React 重渲染次数经 rAF 收敛(非每 mousemove 一次)。
  • 输入框改值后地图预览更新,与拖到同一数值的结果一致。
  • 输入 1.53 后按 Ctrl+Z 一次即回到修改前状态。
  • 输入过程中(如已键入 1.)到达的预览响应不会改写输入框内容。
  • 输入越界值:字段标红、不发预览请求(可由网络面板证明)、保留上一个有效预览、blur 后不产生 undo 步骤。
  • 点击范围提示中的极值可一键填入并正常提交。
  • 拖拽越界时手柄停在极限位置,行为与改动前一致。
  • 未修改参数与显式设为基线值的参数在面板上可区分;"重置"能删除约束并使该行回到未修改态。
  • 影响区间的米↔station 换算函数经单测覆盖,往返无累积漂移。(区间行本身受 intervalEditingSupported 门控,当前不渲染。)
  • 输入未失焦时直接点"保存",该次修改被正确持久化。
  • 路口保留区内的手柄在面板中禁用并显示原因。
  • npm run format:check、npm run test、npm run test:client、npm run test:client:unit、npm run build 全绿。

风险与门槛

  • 面板不得成为第二套几何或第二个值的真相来源。所有范围、位置、影响对象仍只来自服务端 manifest。
  • value.current 是请求值的回显而非求解值。若后续 solver 改成回写求解结果,第 11 条的显示规则失效,必须同步重审。
  • 外缘偏移的 min/max 随道路宽度浮动,因此"当前合法"不等于"永远合法"。客户端校验只能覆盖输入当下。
  • 拖拽回流若实现为直接 setState,会逐帧重渲染 974 行的 App。必须先确认节流有效再扩大面板规模。

已知缺口(不在本任务内)

服务端只校验 finite/非负,不校验 manifest 的 min/max;而外缘偏移范围随道路宽度浮动,意味着保存时合法的值可能在几何变化后越界。这类越界客户端结构上无法拦截——它发生在保存之后的求解期。

design.md 已为 boundaryIndex 定义了同类规则("重放时若车道数变化导致越界,该约束转 stale"),数值范围越界应当同等处理。属重放正确性,独立成任务。