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

119 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 参数面板与数值双向绑定
## 目标
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
## 已确认的事实
以下均为读代码核实,不是推断:
- `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:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。
所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。