Files
road-compiler/.trellis/tasks/archive/2026-09/08-31-constraint-range-validation/prd.md
T

71 lines
5.8 KiB
Markdown

# 约束值范围的服务端校验与重放失效
## 目标
让 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 种已于 2026-08-31 在 `08-28-crosswalk-element-editor` 中修复。**
> `src/compile/crossing-approach.js` 的 `effectiveCrosswalkInsetMax()` 按
> `cutback - max(0, junctionDistance - 4)` 发布真实上界,8 组实测全部吻合,
> 且 fixture 证明几何字节不变。
>
> 本任务因此**只需覆盖其余 kind**——尤其是第 1 种(外缘偏移)。
> 那次修复也给出了可复用的形态:**上界由几何推导,不是常量**;
> 以及一个易犯的坑:一条 segment 的两条方向道路可能在同一路口服务不同对象,
> 取第一个匹配会把 A 的上界发到 B 的手柄上。
第 1 种仍待处理:手柄在死区里拖动毫无反应或直接报错,与「控件坏了」难以区分,
正是 `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` 的「已知缺口」。
- 本任务不阻塞面板任务:面板的客户端校验独立成立。