3.9 KiB
设计:约束范围校验与重放失效
问题边界
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 reasonrange-out-of-bounds;该约束随后不会进入 solver。- 锚点不存在仍是
stale,reason 为anchor-missing。候选可重定位时仍沿用pending/conflicted。
范围校验的阻塞诊断与重放 stale 是两条刻意不同的路径:前者说明本次草稿违法,后者说明曾经合法的历史编辑不再适合新的几何。
API 契约
constraintStates 在原有 status / applied / reason 外,将 reason 标准化为可供 rebase 消费的枚举值:
range-out-of-boundsanchor-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 拒绝,不能把其他约束偷偷改掉。