Files
road-compiler/.trellis/tasks/08-31-constraint-range-validation/prd.md
T
que01andClaude Opus 5 1c27501534 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>
2026-08-31 11:58:00 +08:00

4.5 KiB

约束值范围的服务端校验与重放失效

目标

让 manifest 声明的取值范围与求解器实际接受的可行域一致,并让保存后因几何变化而越界的约束按既有 status 机制转 stale,而不是静默产出畸形几何。

缺口有两个方向,实测确认(见 08-31-parameter-panel-binding/research/manifest-range-vs-solver.md):

  1. 过松——manifest 宣告的范围比求解器接受的宽。实测某 6.5m 道路的外缘偏移手柄声明 ±2.925,但超过约 ±1 即返回 direct-edit-outer-edges-cross。宣告范围约为可行域的 3 倍。
  2. 无校验——求解器不检查 manifest 的 min/max,范围目前仅由客户端夹值实际约束。

方向 1 是用户可直接感知的(拖到一半几何就冻结),优先级高于方向 2。

已确认的事实

  • direct-edit-solver.js 的 applyConstraint 分支(302、312、322 行附近)只校验 Number.isFinite 与非负,未校验 manifest 声明的 min / max。
  • 范围目前是纯客户端概念:manifest 下发它,projection.ts:60 的 projectHandleValue 夹它,仅此而已。今天没出事,只因拖拽是唯一写入通道且它必夹。
  • 部分范围是动态的:外缘偏移为 ±Math.max(0.1, width * 0.45),随道路宽度浮动;步行带固定 0..8;角部圆角固定 0.5..30。
  • 因此保存时合法的值,可能在道路几何变化后越界——重导入改变车道数、其它约束改变断面宽度均可触发。该类越界发生在保存之后的求解期,客户端结构上无法拦截。
  • 父 design.md 已为同类情形定义规则:"boundaryIndex ⋯ 重放时若车道数变化导致越界,该约束转 stale,不做近似映射。"数值范围越界属于同一类,只是未被写下。
  • 08-31-parameter-panel-binding 引入第二条写入通道(数值输入)。该任务在客户端拦截越界输入,但那只覆盖输入当下,不覆盖本任务的场景。

范围

  1. manifest 发布的 min/max 必须落在求解器实际接受的可行域内——宣告一个必被拒绝的极值等于骗用户。
  2. 求解器在应用约束时校验其值落在该 kind / 该锚点当前的合法范围内。
  3. 越界值产生阻塞性诊断,不静默夹值、不静默丢弃。
  4. 范围的计算与 manifest 中 value.min / value.max 的生成共用同一处逻辑,不得出现两份定义。
  5. 重放(重导入、几何版本变更)时,因范围变化而越界的约束转 stale,与 boundaryIndex 越界同等处理。
  6. rebase 响应的 status 计数与明细覆盖这一新的 stale 来源。

明确不做

  • 不改变客户端拖拽的夹值行为(projectHandleValue 是渲染正确性的一部分)。
  • 不为越界约束做近似映射或自动修正——与父 design.md 的"不自动改值"一致。
  • 不新增约束 kind,不改动几何生成。

验收标准

  • 复现 research 记录的场景:某 6.5m 道路的外缘偏移手柄,其发布的 max 不再是一个提交即被 direct-edit-outer-edges-cross 拒绝的值。
  • 对任一手柄,提交恰好等于 manifest min 或 max 的值不产生阻塞诊断(宣告即可用)。
  • 绕过客户端直接 POST 一个越界约束到 /api/edit-preview,返回阻塞性诊断而非畸形几何。
  • manifest 的 min/max 与求解器校验用的范围来自同一处代码,可由测试证明二者一致。
  • 构造一个"保存时合法、几何变化后越界"的场景(如缩窄道路使可行域下降),重放后该约束报 stale,且不参与求解。
  • stale 的原因在 rebase 响应中可区分于锚点丢失导致的 stale。
  • 既有的 exact 约束不因本改动被误判失效——回归现有 revision 编译结果不变。
  • npm run format:check、npm run test、npm run test:client、npm run build 全绿。

风险与门槛

  • 范围收紧可能让既有已保存约束突然变 stale。上线前必须在真实 import 目录上跑一遍,确认影响面,并确保旧 revision 仍可打开并复现原结果(父 design.md 的可复现性要求)。
  • 范围的两份定义(manifest 生成处与校验处)若各写各的,会产生"手柄允许但求解器拒绝"的死区。第 3 条是硬要求。

关联

  • 缺口由 08-31-parameter-panel-binding 的设计过程发现,详见该任务 design.md 的「已知缺口」。
  • 本任务不阻塞面板任务:面板的客户端校验独立成立。