# 参数面板与数值双向绑定 ## 目标 给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。 地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。 ## 已确认的事实 以下均为读代码核实,不是推断: - `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. 拖拽 → 数字 6. 拖拽过程中面板数值实时跟随,与地图 ghost 同步。 7. 高频更新经 rAF 节流,不得每次 mousemove 触发整个 App 重渲染。 ### 3. 数字 → 图形 8. 输入框修改值时走与拖拽相同的 `draftFor` → `PreviewRequester` 链路,含 80ms 防抖与 `previewSeq` 仲裁。 9. gesture 边界:`focus` 对应 `pointerdown`(铸 operationId),`blur` / `Enter` 对应 `pointerup`(`commitGesture`)。输入 `1.53` 只产生**一步** undo。 10. `Escape` 回滚到上一个有效值并 `cancel()` 在途请求。 11. 聚焦期间输入框显示本地文本,失焦后跟随 `value.current`。中间态不被预览响应冲掉。 12. `saveDirectEdits()` 入口先强制结算未闭合的 gesture,不依赖 blur 与 click 的触发顺序。 ### 4. 范围处理 13. 拖拽与滑杆维持夹值(`projectHandleValue` 不变)。 14. 数值输入**不夹值**:越界时标记非法、不发预览、不进 undo 栈,保留最后一个有效预览。 15. 范围提示中的极值可一键填入。 ### 5. 重置 16. 每行提供"重置",删除该约束回到基线。这是拖拽无法表达的操作——拖拽只能设值,不能移除约束。 ## 明确不做 - 不移除、不削弱地图上的拖拽手柄。 - 不新增约束 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:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。 所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。