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>
5.1 KiB
5.1 KiB
约束值范围的服务端校验与重放失效
目标
让 manifest 声明的取值范围与求解器实际接受的可行域一致,并让保存后因几何变化而越界的约束按既有 status 机制转 stale,而不是静默产出畸形几何。
缺口有三种表现,均已实测确认(证据见 08-31-parameter-panel-binding/research/manifest-range-vs-solver.md):
- 过松且会被拒——manifest 宣告的范围比求解器接受的宽。某 6.5m 道路的外缘偏移手柄声明
±2.925,超过约±1即返回direct-edit-outer-edges-cross。宣告范围约为可行域的 3 倍。 - 过松且静默无效——比上一种更糟,因为没有任何反馈。
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% 是死区。 - 无校验——求解器不检查 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引入第二条写入通道(数值输入)。该任务在客户端拦截越界输入,但那只覆盖输入当下,不覆盖本任务的场景。
范围
- manifest 发布的
min/max必须落在求解器实际接受的可行域内——宣告一个必被拒绝的极值等于骗用户。 - 求解器在应用约束时校验其值落在该 kind / 该锚点当前的合法范围内。
- 越界值产生阻塞性诊断,不静默夹值、不静默丢弃。
- 范围的计算与 manifest 中
value.min/value.max的生成共用同一处逻辑,不得出现两份定义。 - 重放(重导入、几何版本变更)时,因范围变化而越界的约束转
stale,与boundaryIndex越界同等处理。 - 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的「已知缺口」。 - 本任务不阻塞面板任务:面板的客户端校验独立成立。