Files
road-compiler/.trellis/tasks/08-31-parameter-panel-binding/prd.md
T

8.9 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"),数值范围越界应当同等处理。属重放正确性,独立成任务。

右侧工作台扩展(2026-09-01)

当前右侧栏将道路基础覆盖、直接编辑参数、路口连接、车道转向箭头、标线样式、 原生信号灯、复杂路口候选和技术 JSON 直接按顺序堆叠,缺少所选对象摘要、明确的 编辑上下文和一致的表单层级。用户确认本轮应覆盖全部既有编辑器,而非只处理道路 参数或车道箭头。

拟纳入范围:

  • 统一右侧栏的对象摘要、未保存/即时保存状态和表单布局。
  • 重新组织道路、元素、连接、调试/技术详情中的全部既有表单与信息展示。
  • 为车道转向箭头补足距路口位置的可读数与精确输入,继续复用 placementDistanceMeters 覆盖和既有拖曳行为。
  • 保持各写入语义:普通 override 继续暂存并经保存/重新生成生效;信号灯继续走 现有即时 API;直接编辑继续走 manifest/preview/session 链路。

已决 UX:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。 所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。