Files
road-compiler/.trellis/tasks/08-31-constraint-range-validation/design.md
T

58 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 设计:约束范围校验与重放失效
## 问题边界
`road-edge-offset` 的 manifest 以 `makeRoadHandles()` 中一个 segment 的双向总宽计算 `±width * 0.45`,而 `applyRoadConstraint()` 针对锚点指向的单条 direction road 执行最小车道宽与外缘边界判定。二者不共享数据和公式,导致已发布的拖拽终点能被求解器拒绝。
范围是锚点在**当前模型和当前已应用截面状态**下的可行域;它不是客户端提示。直接 API、正式编译重放和 manifest 必须对同一个值作同一判断。
## 单一范围所有者
在 `src/compile/direct-edit-solver.js` 增加内部 range resolver。它接收当前 model、constraint/handle anchor,以及已经应用的 road profile 或 junction plan,返回值字段的 `{ min, max }`;无法解析的锚点由现有锚点状态流程处理,而不是伪造范围。
每个已发布 kind 均通过该 resolver 取范围:
- `road-edge-offset`:以锚点所指单条 road 的宽度、车道数及另一侧当前 offset 推导。下限确保总宽不低于 `laneCount * MIN_LANE_WIDTH_METERS`;两侧上限受单侧半宽不变量约束。不能再以 segment 总宽发布范围。
- `road-lane-divider`:按锚点 road 的单车道宽和最小车道宽推导对称范围。
- `road-sidewalk-width`、corner radius、crosswalk size:将现有有限常量移进 resolver。
- approach width、cutback、crosswalk inset、stop-line offset:由对应 approach 与当前 plan 推导;crosswalk inset 延用 `effectiveCrosswalkInsetMax()`,不再让 manifest / apply 分别持有上界。
Resolver 的上界不得低于已保存的 current 值:历史值会先在重放预检中判 stale,只有尚未失效的值才可发布给客户端。这避免“当前值超过 manifest max”的自相矛盾状态。
## 求解与重放
`solveConstraints()` 每次应用 constraint 前,将其与当前 profile/plan 交给 range resolver:
- 预览、保存后重新编译、直接调用 resolver:越界产生阻塞诊断,constraint state 为未应用 `invalid`;不夹值也不写回 document。
- `reconcileConstraints()`:对 `exact` / `recheck` 的已解析锚点,在不改值的前提下按当前几何计算其范围。值越界时将 document 内存副本状态置为 `stale`,并携带不可变的 replay reason `range-out-of-bounds`;该约束随后不会进入 solver。
- 锚点不存在仍是 `stale`,reason 为 `anchor-missing`。候选可重定位时仍沿用 `pending` / `conflicted`。
范围校验的阻塞诊断与重放 stale 是两条刻意不同的路径:前者说明本次草稿违法,后者说明曾经合法的历史编辑不再适合新的几何。
## API 契约
`constraintStates` 在原有 `status` / `applied` / `reason` 外,将 reason 标准化为可供 rebase 消费的枚举值:
- `range-out-of-bounds`
- `anchor-missing`
- 保留已有 `disabled`、`status-*`、`invalid`。
`POST /api/revisions/:id/rebase` 继续返回 status counts 和 constraints 明细;调用方通过每个 stale constraint 的 `reason` 区分范围失效和锚点失效。无 schema 版本变更,旧客户端可忽略新增/更精确的 reason。
## 数据流
```
current model + applied profile/plan
-> constraint range resolver
-> manifest value.min/max
-> preview/formal solver blocking validation
-> reconciliation stale check during replay
-> rebase constraintStates.reason
```
## 兼容性与风险
- 不修改 persisted v2 schema,也不自动夹值、重写 value 或近似映射锚点。
- 新 range 可能使旧文档中先前允许但几何上不可行的值显示为 stale;这是目标行为。上线前在真实 import 目录做 rebase 审计。
- 多条相互影响的 road constraints 仍按文档顺序求解。范围 helper 使用当前已应用 profile,确保 manifest 和本次 solver 的单值判断一致;组合造成的后续不变量失败仍由现有事务式 solver 拒绝,不能把其他约束偷偷改掉。