Files
road-compiler/.trellis/tasks/08-31-constraint-range-validation/prd.md
T
que01andClaude Opus 5 4b70b0221d docs: record the crosswalk inset dead zone
Sweeping the declared [0, 8] range and measuring where the group actually lands:
0 to 3.2 tracks one-to-one, and 3.2 to 8 does not move at all. No diagnostic, no
feedback — roughly 60% of the advertised range is inert.

crossingJunctionInset() drives it. targetDistance bottoms out once inset reaches
the approach's cutback, and a 4m cap sits above that, so the real ceiling varies
per approach while the manifest publishes a flat 8 for all of them.

This is worse than the edge-offset case already on file. That one refuses and
says so; this one silently does nothing, which is indistinguishable from a broken
control — the exact failure the interval flag exists to prevent, occurring in the
upper half of a range rather than across a whole handle. A user whose first drag
lands in the dead zone concludes direct editing does not work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 14:11:57 +08:00

5.1 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. 过松且静默无效——比上一种更糟,因为没有任何反馈。junction-crosswalk-inset 声明 [0, 8],实测 0 → 3.2 线性响应,3.2 → 8 位移增量全为 0。成因是 crossingJunctionInset() 中 targetDistance = max(0, cutbackMeters - inset) 在 inset 达到 cutbackMeters 后触底,外加 CROSSWALK_MAX_JUNCTION_INSET_METERS = 4 的封顶。声明范围里约 60% 是死区。
  3. 无校验——求解器不检查 manifest 的 min/max,范围目前仅由客户端夹值实际约束。

第 2 种最需要优先修:手柄在死区里拖动毫无反应,与「控件坏了」无法区分, 正是 flag.ts 为 profile.interval 立下的那条规矩要避免的情形 (「一个拖了没效果的控件比没有控件更糟」),只是它发生在量程的上半段而非整个控件。

已确认的事实

  • 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 的「已知缺口」。
  • 本任务不阻塞面板任务:面板的客户端校验独立成立。