chore(tasks): archive completed edit workflows
This commit is contained in:
1 parent
a78f5257fc
commit
39d7453ebc
13 files changed
+4
-4
No files matched your search
@@ -0,0 +1,118 @@
|
||||
# 参数面板与数值双向绑定
|
||||
|
||||
## 目标
|
||||
|
||||
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
|
||||
|
||||
地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
以下均为读代码核实,不是推断:
|
||||
|
||||
- `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:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。
|
||||
所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。
|
||||
Reference in new issue
Block a user