feat: edit road parameters by number as well as by drag

The map had one input device. A drag projects a pointer onto the manifest's
axis; there was no way to state a value, read one, or withdraw one.

Both channels now meet at the same three exits in App.tsx — draftValue()
previews, settleValue() commits one undoable command, abandonGesture() puts the
settled state back — so nothing about the constraint, the debounce or the
previewSeq arbitration is implemented twice. EditSession is untouched: focus and
blur land on the gesture boundary that pointerdown and pointerup already used,
which is why typing 1.53 is one undo step rather than four.

Three rules the two devices do not share:

- Live drag values bypass React and write the input's value directly, per
  direct-edit-client.md §7. A layout effect re-applies them after a mid-drag
  preview replaces the manifest, and drops the override once the manifest
  reports the value the drag asked for.
- Typed values out of range are refused, not clamped. A pointer cannot state an
  intent it never reached, so a drag clamps; typed text is an intent, and a
  clamped typo reads as a plausible value that can go unnoticed. The offered
  extremes round inward — a real max of 2.925 renders as 2.93 under
  nearest-rounding, which the range it came from would then reject.
- Reset disables the constraint rather than deleting it: validateEditDocument()
  rejects an operation naming a constraint that is not in the document. This is
  the one edit a drag cannot express, since a drag can set a value but never
  withdraw one.

Interval editing stays behind intervalEditingSupported, which is still false —
compileGeometry() does not read profile.interval, and a control that changes
nothing is worse than no control. The conversions are implemented and tested so
the row appears when the flag flips.

Probing a live manifest turned up a defect that is not from this change and is
not fixed here: an edge offset advertises ±2.925 while the solver rejects past
about ±1. Evidence is in the task's research/, and the requirement moved to
08-31-constraint-range-validation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
que01andClaude Opus 5 committed 2026-08-31 11:58:00 +08:00
1 parent 5e4e42c46f
commit 1c27501534
17 files changed
+1335 -15

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,114 @@
# 参数面板与数值双向绑定 · 设计
> 父任务 `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`,不做近似映射"——数值范围越界应同等处理。
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
@@ -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,84 @@
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
## 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`:**本任务不改**。若发现必须改,先确认不是把服务端校验缺口混进了本任务范围。
@@ -0,0 +1,99 @@
# 参数面板与数值双向绑定
## 目标
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
## 已确认的事实
以下均为读代码核实,不是推断:
- `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`"),数值范围越界应当同等处理。属重放正确性,独立成任务。
@@ -0,0 +1,58 @@
# 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` 的需求。
@@ -0,0 +1,26 @@
{
"id": "parameter-panel-binding",
"name": "parameter-panel-binding",
"title": "参数面板与数值双向绑定",
"description": "为直接编辑加参数面板:数值输入与地图拖拽双向绑定,共用同一条约束/预览/undo 链路",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-31",
"completedAt": null,
"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": {}
}