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,4 @@
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"检查面板未写入 baseline source、控件值全部由 manifest 驱动、previewSeq 仲裁未被绕开。"}
|
||||
{"file":".trellis/spec/frontend/state-management.md","reason":"检查聚焦/失焦的值所有权切换无第二真相来源,且中间态不被预览响应改写。"}
|
||||
{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"检查新增纯逻辑的单测覆盖与客户端质量门槛。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"核对拖拽与输入两条通道汇合于同一个 draftFor,未出现并行实现。"}
|
||||
@@ -0,0 +1,138 @@
|
||||
# 参数面板与数值双向绑定 · 设计
|
||||
|
||||
> 父任务 `08-26-direct-manipulation-road-editor/design.md` 仍是约束模型、求解边界与 API 合约的权威定义。本文只补充**第二条输入通道**引入的规则,不改变其中任何一条。
|
||||
|
||||
## 架构定位
|
||||
|
||||
本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层:
|
||||
|
||||
```text
|
||||
┌─ 拖拽(连续)──→ projectHandleValue() ─┐
|
||||
选中道路 → manifest ─┤ ├→ draftFor(handle, value)
|
||||
└─ 输入框(离散)→ 解析 + 范围校验 ──────┘ ↓
|
||||
PreviewRequester
|
||||
(80ms 防抖 + previewSeq 仲裁)
|
||||
↓
|
||||
EditSession.commit()
|
||||
```
|
||||
|
||||
`draftFor(handle, value)`(`App.tsx:206`)本就是纯函数 `(手柄, 数字) → 草稿`。两条通道的唯一区别是**如何产生那个数字**以及**何时闭合 gesture**,汇合点之后完全一致。
|
||||
|
||||
## 不变量:取值范围
|
||||
|
||||
> **约束值永不超出 manifest 声明的 `[min, max]`。**
|
||||
>
|
||||
> - **连续输入**(拖拽、滑杆)在极限处**停止移动**。ghost 与手柄按夹后的值绘制,绝不跟随越界的光标。
|
||||
> - **离散输入**(数值框)**拒绝接受**越界值:标记非法、不发预览、不进 undo 栈、保留最后一个有效预览。范围提示可一键填入极值。
|
||||
|
||||
这是**一条规则的两种设备表达**,不是两套策略。
|
||||
|
||||
连续设备没有表达"拒绝"的手段——停止移动就是它的拒绝,而且是当场可见的:手柄停住、光标继续走。用户不会形成"我设成了 -24.1"这个信念。夹值理由见 `projection.ts:75` 的注释(ol-ext 探针把手柄拖到 -24.1m 而约束夹在 -5.4m,手柄指向一个不可能存在的路形)。
|
||||
|
||||
离散设备则相反:数字已经键入、Tab 已经按下,此时夹值是**事后篡改**。且失败模式不对称——
|
||||
|
||||
| 用户意图 | 夹值 | 拒绝 |
|
||||
| --- | --- | --- |
|
||||
| 打错(想输 2.4,输成 24) | 变成 5.4,看起来合理,可能永不被发现 | 立即可见 |
|
||||
| 想拉满 | 如愿 | 多一步(或点范围提示一键填入) |
|
||||
|
||||
拒绝错了只损失一次击键;夹值错了会把一个**看起来正常的错误值**送进下游编译与仿真。故取拒绝。
|
||||
|
||||
## 值的所有权
|
||||
|
||||
任一时刻,一个参数的显示值来源是**唯一**且由聚焦状态决定的:
|
||||
|
||||
| 状态 | 显示值 | 理由 |
|
||||
| --- | --- | --- |
|
||||
| 未聚焦 | `handle.value.current` | 服务端权威回显 |
|
||||
| 聚焦中 | 本地文本 draft | 保留 `1.`、`-`、空串等中间态 |
|
||||
|
||||
必须如此的原因:`App.tsx:197` 在每次预览结算时 `setManifest(response.handles)` 整体替换 manifest。受控输入若直接绑定 `value.current`,键入 `1.` 触发的防抖预览返回后会把输入框冲成 `1`,小数点消失。
|
||||
|
||||
失焦即清 draft。此时 `value.current` 必然等于刚提交的值——因为 `direct-edit-solver.js:136` 的 `numericValue()` 直接回显约束里的数字,服务端不改写。**故不存在"请求值 vs 求解值"的双显示需求。**
|
||||
|
||||
> 该结论依赖 solver 当前行为。若日后改为回写求解结果,本节规则失效,需同步重审。
|
||||
|
||||
## gesture 边界
|
||||
|
||||
`gestureIdentity()` 是懒创建的 operationId 单例,`commitGesture()` 释放它。它抽象的是"一段有始有终的操作",与指针无绑定关系,因此可原样承载键盘输入:
|
||||
|
||||
| 阶段 | 拖拽 | 输入框 | 动作 |
|
||||
| --- | --- | --- | --- |
|
||||
| 开始 | `pointerdown` | `focus` | 铸 operationId |
|
||||
| 进行 | `pointermove` | `onChange` | `requester.schedule()`,**不 commit** |
|
||||
| 结束 | `pointerup` | `blur` / `Enter` | `requester.flush()` + `commitGesture()` |
|
||||
| 放弃 | — | `Escape` | 回滚显示值 + `requester.cancel()` |
|
||||
|
||||
`EditSession` 与 `gestureIdentity()` 无需改动。输入 `1.53` 产生一步 undo,而非四步。
|
||||
|
||||
滑杆(若实现)的 pointerdown/up 天然落在此表内,不引入新分支。
|
||||
|
||||
**保存路径**:`saveDirectEdits()` 必须在入口强制结算未闭合的 gesture。DOM 中 blur 先于 click 触发,直接点"保存"能赶上,但该顺序过于脆弱,不作为正确性依赖。
|
||||
|
||||
## 区间的单位分层
|
||||
|
||||
父 `design.md` 的坐标分层表规定持久化层只有米与归一化 station。显示层不受该表约束。
|
||||
|
||||
| 层 | 单位 |
|
||||
| --- | --- |
|
||||
| 持久化 / 传输 | `station` (0..1) |
|
||||
| 面板显示与输入 | 米(`station × roadLengthMeters`) |
|
||||
|
||||
**只在用户实际编辑时换算**,不在每次渲染时做 米→station→米 的往返,否则四舍五入会让数字自行漂移。`roadLengthMeters` 取自 `IntervalRangeHandle`,与 range 手柄同源。
|
||||
|
||||
区间由整条道路共享(`rangeDraftFor` 重锚该路全部约束),故在面板中**每条路一行**,不随手柄重复。
|
||||
|
||||
## 面板可表达而拖拽不能表达的操作
|
||||
|
||||
`value.current` 在无约束时回落基线(外缘偏移基线为 0),因此"未修改"与"显式设为 0"数值完全相同。`handle.constraintId` 仅在约束存在时出现,客户端据此区分。
|
||||
|
||||
由此得到一个拖拽结构上无法提供的能力:**删除约束**。拖拽只能设值,不能移除。面板每行提供"重置",删除该约束并使该行回到未修改态。
|
||||
|
||||
这是参数面板的实质增量,而非拖拽的镜像显示。
|
||||
|
||||
## 渲染性能
|
||||
|
||||
`handleDragEvent` 每次 mousemove 触发,而 `App.tsx` 是单个 974 行组件。拖拽值回流面板必须经 rAF 节流,不得直接 `setState`。
|
||||
|
||||
节流有效性需在扩大面板规模前验证——手柄当前仅 5~6 个,问题不会自行显现。
|
||||
|
||||
## 边界
|
||||
|
||||
- 面板不得成为第二套几何算法或第二个值的真相来源。范围、位置、`affects`、可编辑性一律只来自服务端 manifest。
|
||||
- 面板只呈现主地图拥有的 kind。路口 shape 三 kind 仍属 `JunctionTools`;保留区内手柄呈禁用态并显示 `disabledReason`。
|
||||
- 不新增约束 kind,不改动求解器。
|
||||
|
||||
## 已知缺口
|
||||
|
||||
服务端 `applyConstraint` 只校验 `Number.isFinite` 与非负,**不校验 manifest 的 `min`/`max`**。今日范围仅由客户端 `projectHandleValue` 的夹值实际约束。
|
||||
|
||||
外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`),因此保存时合法的值可能在后续几何变化后越界。此类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
|
||||
|
||||
父 `design.md` 已为 `boundaryIndex` 定义同类规则——"重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射"——数值范围越界应同等处理。
|
||||
|
||||
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
|
||||
|
||||
## 右侧工作台信息架构(2026-09-01)
|
||||
|
||||
右栏是操作面板而非信息流。顶部固定呈现当前选择对象、其道路方向和修改状态;下方
|
||||
采用单主展开区的手风琴,避免所有表单在初始状态占满地图旁的空间。
|
||||
|
||||
| 分段 | 内容 | 展开规则 | 写入语义 |
|
||||
| --- | --- | --- | --- |
|
||||
| 道路 | 基础道路覆盖、直接编辑参数 | 选中道路时默认展开 | override 暂存;直接编辑 preview/session |
|
||||
| 元素 | 车道箭头、标线、信号灯 | 选择相应地图元素时自动展开 | 箭头/标线暂存;信号灯即时 API |
|
||||
| 连接 | 路口连接、行驶动作、手工候选 | 默认收起 | override 暂存 |
|
||||
| 高级 | 复杂路口候选、技术 JSON | 始终默认收起 | 候选沿用现有调用 |
|
||||
|
||||
每个分段使用受控 React 状态,而非依赖原生 `<details>` 的不可观察状态;这让地图选中
|
||||
事件可以可靠地展开相应段,且移动端与桌面端保持同一状态模型。分段标题显示摘要
|
||||
(如参数修改数、所选第几车道、连接数量),但不复制任何几何或约束值。
|
||||
|
||||
车道箭头在元素段显示 maneuver 选择、距路口端的米数读数和有限数值输入。数值输入与
|
||||
拖曳都写同一 `lane-maneuver.placementDistanceMeters`;客户端只限制为有限非负值,控制
|
||||
设施与端点安全位置仍由正式编译的 `nearestSafeTurnArrowPlacement()` 权威裁决。
|
||||
|
||||
为避免继续膨胀 `App.tsx`,右栏容器、对象摘要、手风琴、道路/连接/元素分段应迁入
|
||||
`workbench/client/src/components/`。现有 `ParameterPanel` 保持其 manifest 值所有权和
|
||||
DOM 直写性能策略,只作为“道路”分段的内容,不被重写为另一条输入链路。
|
||||
@@ -0,0 +1,6 @@
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"面板是第二条输入通道,必须继续遵守 manifest 驱动、baseline 不被写入、预览时序与图层所有权。"}
|
||||
{"file":".trellis/spec/frontend/state-management.md","reason":"聚焦期本地 draft 与服务端 value.current 的所有权切换是本任务的核心状态规则,不得产生第二个值的真相来源。"}
|
||||
{"file":".trellis/spec/frontend/component-guidelines.md","reason":"新增参数面板组件需符合既有组件结构与职责边界。"}
|
||||
{"file":".trellis/spec/frontend/hook-guidelines.md","reason":"拖拽回流的 rAF 节流以 hook 承载,需符合既有 hook 约定。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"输入通道必须复用 draftFor / PreviewRequester / EditSession,禁止复制出第二套预览与 undo 链路。"}
|
||||
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 约束模型、坐标分层、预览时序与 handle manifest 的权威合同。"}
|
||||
@@ -0,0 +1,97 @@
|
||||
# 实施计划
|
||||
|
||||
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
|
||||
|
||||
## 0. 纯逻辑与测试夹具
|
||||
|
||||
- 在 `workbench/client/src/edit/` 新增参数值的纯逻辑:数值格式化/解析(保留 `1.`、`-`、空串中间态)、范围校验、`station ↔ 米` 换算。
|
||||
- 与现有 `meters.ts` / `projection.ts` / `selection.ts` 同侧,**不得 import OpenLayers**。
|
||||
- 失败优先的 vitest:越界判定的边界值、中间态解析不丢字符、米↔station 往返不漂移。
|
||||
- 门禁:新增模块的单测在 node 下跑通,且 `grep -r "from 'ol" ` 对新文件无命中。
|
||||
|
||||
## 1. 面板只读渲染
|
||||
|
||||
- 新增面板组件,遍历 `editHandles` 渲染:中文名、`value.current`、单位、`[min, max]`。**此步不可编辑。**
|
||||
- 多个 `road-lane-divider` 按 `boundaryIndex` 分行;不可编辑手柄呈禁用态并显示 `disabledReason`。
|
||||
- 依 `handle.constraintId` 是否存在标记"已修改"。
|
||||
- 区间每条路一行,以米显示。
|
||||
- 验证:选中不同道路、选中含保留区的道路、选中多车道道路,面板结构正确。
|
||||
- 门禁:`directEdit` 开关关闭时面板不渲染、不请求 manifest,网络轨迹与 main 一致。
|
||||
|
||||
## 2. 拖拽 → 面板回流
|
||||
|
||||
- 拖拽值**直接写 DOM 节点**(ref + `textContent` / `value`),不经 React 渲染。
|
||||
`direct-edit-client.md` §7:rAF 合并是**最低要求**,"写到源头"才是生产规则;ghost 直接写 OL source,面板的等价物是直接写 DOM。
|
||||
- **禁止**在 `handleDragEvent` 中 `setState`;gesture 结束时才做一次 state 对账。
|
||||
- 禁止在 `setState` updater 内计算或读 OL 状态(§6)。
|
||||
- 验证:拖拽过程中面板数值实时跟随;用 render 计数确认**面板未新增任何渲染**。
|
||||
注意门禁不是"拖拽期间渲染 0 次"——`onSettled` 的 `setManifest` 本就会在拖拽中随防抖预览触发渲染,那是服务端权威预览的固有代价,改动前就存在。要证明的是 `pointermove` 自身不再产生渲染。
|
||||
- 拖拽中落地的预览会把 manifest 换成滞后一个防抖周期的值,需保证数字不在两者间闪烁。
|
||||
- 门禁:节流有效性必须在此步证明。手柄当前仅 5~6 个,问题不会自行显现;跳过则后续无从归因。
|
||||
|
||||
## 3. 输入通道:预览、gesture 边界、commit
|
||||
|
||||
- 输入框接入 `draftFor` → `PreviewRequester.schedule()`,复用 80ms 防抖与 `previewSeq` 仲裁。
|
||||
- gesture 边界按 `design.md` 表实现:`focus` 铸 operationId,`onChange` 只预览,`blur` / `Enter` 走 `flush()` + `commitGesture()`,`Escape` 回滚 + `cancel()`。
|
||||
- 聚焦期间显示本地文本 draft,失焦后跟随 `value.current`。
|
||||
- **`EditSession` 与 `gestureIdentity()` 不得修改**;若发现需要改,说明边界映射错了,退回重审。
|
||||
- 验证:输入框改值与拖到同一数值产出同形约束;输入 `1.53` 后一次 Ctrl+Z 回到修改前;键入 `1.` 期间到达的预览响应不改写输入框。
|
||||
- 门禁:一次非空表单编辑可在正式重编译结果中观察到几何变化。只交付 UI 不算通过。
|
||||
|
||||
## 4. 范围拒绝与极值填入
|
||||
|
||||
- 越界输入:标红、**不发预览请求**、不进 undo 栈、保留最后一个有效预览。
|
||||
- 拖拽与滑杆的夹值行为保持不变(`projectHandleValue` 不改)。
|
||||
- 范围提示中的极值可点击填入。
|
||||
- 验证:越界时网络面板无新请求;blur 后无新 undo 步骤;点击极值可正常提交;拖拽越界时手柄仍停在极限。
|
||||
- 门禁:夹值与拒绝的差异必须体现为 `design.md` 中的同一条不变量,不得实现成两条并列策略。
|
||||
|
||||
## 5. 重置与区间换算
|
||||
|
||||
- 每行"重置"删除该约束,使该行回到未修改态(`constraintId` 消失、值回落基线)。
|
||||
- 区间的米↔station 换算实现并单测;**区间行受 `intervalEditingSupported` 门控,当前为 `false` 故不渲染**。
|
||||
理由与 range 手柄一致(`flag.ts:46`):`compileGeometry()` 不读 `profile.interval`,一个改了没效果的输入框比没有更糟。
|
||||
换算只在用户实际编辑时进行,渲染路径不做米→station→米 往返。
|
||||
- 验证:重置后保存重编译,该参数回到基线;换算函数往返无累积漂移;开关为 `false` 时面板不出现区间行。
|
||||
|
||||
## 6. 加固与手测
|
||||
|
||||
- `saveDirectEdits()` 入口强制结算未闭合 gesture,不依赖 blur/click 顺序。
|
||||
- 手测清单:
|
||||
- 输入未失焦直接点"保存",修改被正确持久化。
|
||||
- 拖拽与输入交替操作,undo/redo 序列正确。
|
||||
- 快速连续输入,乱序预览响应不覆盖较新结果。
|
||||
- 切换选中道路时未闭合的输入被正确结算或放弃。
|
||||
- OpenLayers `Map` 未被重建,仅受影响 source 被替换。
|
||||
- 门禁:交付前 `directEdit` 开关行为与改动前一致。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run test:client:unit
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 风险文件
|
||||
|
||||
- `workbench/client/src/App.tsx`:974 行单组件。面板 state 与拖拽回流都落在此处,是重渲染风险的集中点;必要时先抽出编辑状态再加面板。
|
||||
- `workbench/client/src/edit/session.ts`:**不应修改**。若实现中需要改动,说明 gesture 边界映射有误。
|
||||
- `workbench/client/src/edit/projection.ts`:`projectHandleValue` 的夹值是拖拽正确性的一部分(见其 75 行注释),不得为"统一行为"而移除。
|
||||
- `workbench/client/src/edit/preview-request.ts`:防抖与 `previewSeq` 仲裁由两条通道共用,任何改动同时影响拖拽。
|
||||
- `src/compile/direct-edit-solver.js`:**本任务不改**。若发现必须改,先确认不是把服务端校验缺口混进了本任务范围。
|
||||
|
||||
## 右侧工作台扩展(2026-09-01)
|
||||
|
||||
1. 抽出受控手风琴和选择对象摘要组件,建立“道路 / 元素 / 连接 / 高级”四段及其
|
||||
自动展开规则;先用静态现有内容验证不改变写入行为。
|
||||
2. 将现有 `Inspector` 的道路覆盖、连接、候选和技术详情迁入对应分段;将标线、箭头、
|
||||
信号迁入元素分段。保留 `ParameterPanel` 的 API 和直接编辑数据流。
|
||||
3. 补充箭头位置的米数读数和精确输入,与拖曳使用同一 staged override;输入非法值不暂存。
|
||||
4. 用组件/纯逻辑单测覆盖自动展开、分段摘要、箭头位置写入和不同写入语义;手测桌面及
|
||||
窄屏的空间、焦点和滚动。
|
||||
5. 执行 `npm run format:check`、`npm run test`、`npm run test:client`、
|
||||
`npm run test:client:unit`、`npm run build`,并验证选箭头、标线、信号、道路与连接的
|
||||
现有保存流程未回归。
|
||||
@@ -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:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。
|
||||
所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
# manifest 范围与求解器可行域不一致
|
||||
|
||||
日期:2026-08-31
|
||||
来源:`08-31-parameter-panel-binding` 实施期间对运行中工作台(`osm-KZZP9U`)的实测。
|
||||
|
||||
## 现象
|
||||
|
||||
手柄 `handle:road-edge-offset:segment:way/-3246/0:left`,manifest 声明
|
||||
`value.min = -2.925`、`value.max = 2.925`(即 `±width * 0.45`,道路宽 6.5m)。
|
||||
|
||||
逐值探测 `POST /api/edit-preview`:
|
||||
|
||||
| offsetMeters | 阻塞诊断 |
|
||||
| --- | --- |
|
||||
| -2.90 | `direct-edit-outer-edges-cross` |
|
||||
| -2.00 | `direct-edit-outer-edges-cross` |
|
||||
| -1.00 | `direct-edit-outer-edges-cross` |
|
||||
| **-0.50** | **(无)** |
|
||||
| **0.00** | **(无)** |
|
||||
| **0.50** | **(无)** |
|
||||
| **1.00** | **(无)** |
|
||||
| 2.00 | `direct-edit-outer-edges-cross` |
|
||||
| 2.90 | `direct-edit-outer-edges-cross` |
|
||||
| 500 | `direct-edit-outer-edges-cross` |
|
||||
|
||||
探针构造已排除误报:小幅值干净,说明请求本身合法。
|
||||
|
||||
## 结论
|
||||
|
||||
**manifest 宣告的范围比求解器实际接受的可行域宽约 3 倍,且双向都是。**
|
||||
真实边界落在 `(-1.0, -0.5]` 与 `[1.0, 2.0)` 之间,未进一步二分。
|
||||
|
||||
失败原因未查明。`direct-edit-outer-edges-cross` 对应 design.md 的
|
||||
「同一站点左右外缘不得交叉」不变量,但仅移动**单侧**外缘 1m
|
||||
(6.5m 宽的路)为何会触发交叉,需要读 `compileGeometry()` 才能确定——
|
||||
可能经由车道最小宽度 2.4m 派生,也可能诊断名不完全对应其实际判据。
|
||||
|
||||
## 与既有行为的关系
|
||||
|
||||
这不是本任务引入的。拖拽一直夹到 `±2.925`,所以用户一直能拖进被拒区间——
|
||||
拖过约 1m 后几何冻结、诊断出现,而手柄继续走到 2.925。
|
||||
按 design.md「无效草稿不替换最后一个有效预览」,这是既定行为。
|
||||
|
||||
参数面板没有改变它,但**把它变可见了**:范围以文字打印,且极值可一键填入。
|
||||
点击极值会得到一个必被服务端拒绝的值。
|
||||
|
||||
## 处理
|
||||
|
||||
未在本任务修改。理由:
|
||||
|
||||
- 客户端范围校验必须用 manifest 的 `min`/`max`,用别的就是发明第二个真相来源
|
||||
(`direct-edit-client.md` §2)。
|
||||
- 收窄范围需要求解器解析地算出外缘交叉的可行区间,属求解器工作,
|
||||
本任务明确排除。
|
||||
- 点击极值的结果是一个诚实的服务端拒绝:诊断可见、最后一个有效预览保留、可撤销。
|
||||
不是静默破坏。
|
||||
|
||||
已并入 `08-31-constraint-range-validation` 的需求。
|
||||
|
||||
---
|
||||
|
||||
# 追加:`junction-crosswalk-inset` 的静默死区
|
||||
|
||||
日期:2026-08-31,区域 `nantaizihu-9PTsZg`。
|
||||
|
||||
手柄 `handle:junction-crosswalk-inset:node/1140799725:segment:way/-3246/0`
|
||||
声明 `value.min = 0`、`value.max = 8`。逐值提交预览并测量该组 6 条斑马线的中心位移:
|
||||
|
||||
| inset | 相对 inset=0 的位移 | 增量 |
|
||||
| --- | --- | --- |
|
||||
| 0 | 0.00 | — |
|
||||
| 0.5 | 0.50 | +0.50 |
|
||||
| 1.0 | 1.00 | +0.50 |
|
||||
| 2.0 | 2.00 | +0.50 |
|
||||
| 3.0 | 3.00 | +0.50 |
|
||||
| 4.0 | 3.20 | +0.20 |
|
||||
| 5.0 | 3.20 | **+0.00** |
|
||||
| 6.0 | 3.20 | **+0.00** |
|
||||
| 8.0 | 3.20 | **+0.00** |
|
||||
|
||||
`0 → 3.2` 是干净的 1:1 线性响应;`3.2 → 8` **完全无响应,且无任何诊断**。
|
||||
|
||||
## 成因
|
||||
|
||||
`crossingJunctionInset()`(`native-road.js:1325`):
|
||||
|
||||
```js
|
||||
const targetDistance = Math.max(0, plan.cutbackMeters - inset);
|
||||
return Math.min(CROSSWALK_MAX_JUNCTION_INSET_METERS,
|
||||
Math.max(0, candidate.junctionDistanceMeters - targetDistance));
|
||||
```
|
||||
|
||||
inset 增至 `plan.cutbackMeters` 后 `targetDistance` 触底为 0,再增无效;
|
||||
外层 `CROSSWALK_MAX_JUNCTION_INSET_METERS = 4` 另有封顶。
|
||||
因此有效上界是 `min(cutbackMeters, …)` 的某个函数,**逐进口不同**,
|
||||
而 manifest 对所有进口一律发布固定的 `max: 8`。
|
||||
|
||||
## 为何比外缘偏移那例更严重
|
||||
|
||||
外缘偏移越界会返回阻塞诊断——用户看得到"不行"。
|
||||
本例越界**什么都不发生**:拖动手柄,几何纹丝不动,没有诊断、没有提示。
|
||||
与「控件坏了」无法区分。
|
||||
|
||||
这正是 `flag.ts` 为 `profile.interval` 立下的规矩所要避免的
|
||||
(「一个拖了没效果的控件比没有控件更糟」),区别只在于它发生在量程的上半段,
|
||||
而不是整个控件。
|
||||
|
||||
若用户在已处于死区的进口上首次尝试拖拽,得到的印象就是"直接编辑不工作"。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "parameter-panel-binding",
|
||||
"name": "parameter-panel-binding",
|
||||
"title": "参数面板与数值双向绑定",
|
||||
"description": "为直接编辑加参数面板:数值输入与地图拖拽双向绑定,共用同一条约束/预览/undo 链路",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-31",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in new issue
Block a user