fix(compile): validate direct edit constraint ranges
This commit is contained in:
1 parent
bb108267e3
commit
0318876e6a
7 files changed
+238
-11
No files matched your search
@@ -40,6 +40,10 @@ POST /api/revisions/:id/rebase
|
||||
- `POST /api/revisions/:id/rebase` is read-only and returns status counts plus
|
||||
per-constraint details. `pending`, `conflicted`, and `stale` constraints do
|
||||
not enter geometry solving.
|
||||
- A resolved constraint whose saved numeric value no longer fits the current
|
||||
geometry range is returned as `stale` with reason `range-out-of-bounds`.
|
||||
A missing replay anchor uses reason `anchor-missing`; callers must not infer
|
||||
the stale cause from the status alone.
|
||||
|
||||
## 4. Validation & Error Matrix
|
||||
|
||||
@@ -53,6 +57,7 @@ POST /api/revisions/:id/rebase
|
||||
| Solver replay anchor cannot resolve | Mark `stale` or `conflicted` with diagnostic; never silently apply |
|
||||
| Compiler geometry version differs | Mark all replayable constraints `recheck` without changing values |
|
||||
| Invariant violation (lane width, crossing boundaries, self-intersection, connector bounds) | Return a blocking diagnostic; do not clamp or silently repair |
|
||||
| Constraint value outside the current handle range | Return a blocking diagnostic; do not clamp or silently repair |
|
||||
|
||||
## 5. Good / Base / Bad Cases
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# 设计:约束范围校验与重放失效
|
||||
|
||||
## 问题边界
|
||||
|
||||
`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 拒绝,不能把其他约束偷偷改掉。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 实施计划:约束范围校验与重放失效
|
||||
|
||||
## 实施顺序
|
||||
|
||||
1. 在 `direct-edit-solver.js` 搜索所有 manifest 与 apply 分支中的范围常量,建立 anchor/context-aware range resolver,并为 road/junction kind 迁移已有边界。
|
||||
2. 让 `makeRoadHandles()` / `makeJunctionHandles()` 从该 resolver 填充 `value.min` / `value.max`;road edge 使用单向 road 和该 side 的 profile,移除 segment 总宽 `0.45` 公式。
|
||||
3. 在 `applyRoadConstraint()`、`applyJunctionConstraint()` 写入前调用相同 resolver,越界使用 kind 明确的 blocking diagnostic,保留现有 rollback snapshot 行为。
|
||||
4. 扩展 `reconcileConstraints()`:已解析、可重放的值若落在新几何范围外则变为 `stale`,并发出 `range-out-of-bounds`;锚点缺失变为 `anchor-missing`,不破坏 pending/conflicted 逻辑。
|
||||
5. 确认 `rebaseEdits()` 的现有 constraint 明细透传 reason;必要时为 response contract 补稳定字段和测试。
|
||||
6. 追加 unit tests:外缘 extrema、直接越界诊断、manifest/solver 同源、几何缩窄后的 stale、不参与求解、anchor stale reason、既有 exact 回归。
|
||||
7. 追加 API integration tests:`editPreview()` 越界诊断与 `rebaseEdits()` reason/counts。
|
||||
8. 按项目质量门槛运行 format、unit/integration/client/build;对真实 import 做只读 rebase 审计并记录受影响约束数。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run build
|
||||
```
|
||||
|
||||
测试重点不只比较 manifest 数字,还要把 manifest 的每个端点实际提交给 resolver,确认没有 blocking diagnostic。重放测试必须断言 stale constraint 未出现在 road profile / junction plan。
|
||||
|
||||
## 风险点与回退
|
||||
|
||||
- 风险文件:`src/compile/direct-edit-solver.js`。范围 helper 若错误共享 segment 与 direction 宽度,会再次出现 handle / solver 不一致;新增 fixture-style unit case 固化双向道路场景。
|
||||
- 兼容性:保留 v2 文档、constraint kind、status 集合与 API 主字段。reason 仅增加细分值。
|
||||
- 回退:本改动不迁移或覆写存储。若真实目录审计发现意外大量 stale,回退代码即可恢复旧行为,原始 edit documents 不受影响。
|
||||
@@ -3,7 +3,7 @@
|
||||
"name": "constraint-range-validation",
|
||||
"title": "约束值范围的服务端校验与重放失效",
|
||||
"description": "服务端补 manifest min/max 校验;保存后因几何变化导致的数值越界转 stale",
|
||||
"status": "planning",
|
||||
"status": "in_progress",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
|
||||
@@ -75,7 +75,13 @@ function emptyHandleManifest(context) {
|
||||
}
|
||||
|
||||
function constraintState(constraint, applied, reason) {
|
||||
return { constraintId: constraint.id, kind: constraint.kind, status: constraint.status, applied, reason };
|
||||
return {
|
||||
constraintId: constraint.id,
|
||||
kind: constraint.kind,
|
||||
status: constraint.status,
|
||||
applied,
|
||||
reason: constraint.status === 'stale' && constraint.replayReason ? constraint.replayReason : reason,
|
||||
};
|
||||
}
|
||||
|
||||
function coordinateAt(line, station) {
|
||||
@@ -221,12 +227,19 @@ function reconcileConstraints(model, constraints, base, junctionData, context) {
|
||||
if (constraint.kind.startsWith('road-')) {
|
||||
const road = roadForAnchor(model, constraint.anchor.roadId);
|
||||
matched = Boolean(road);
|
||||
const roadExists = matched;
|
||||
if (matched && constraint.kind === 'road-lane-divider')
|
||||
matched = Number.isInteger(constraint.value?.boundaryIndex) && constraint.value.boundaryIndex < road.laneCount;
|
||||
if (!matched) {
|
||||
const candidates = snapshotCandidates(model, constraint);
|
||||
if (candidates.length === 1) return { ...constraint, status: 'pending' };
|
||||
return { ...constraint, status: candidates.length > 1 ? 'conflicted' : 'stale' };
|
||||
return {
|
||||
...constraint,
|
||||
status: candidates.length > 1 ? 'conflicted' : 'stale',
|
||||
...(candidates.length || !roadExists
|
||||
? { replayReason: candidates.length ? undefined : 'anchor-missing' }
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
} else if (constraint.kind === 'junction-corner-radius') {
|
||||
const approaches = junctionData.approaches.get(String(constraint.anchor.nodeId));
|
||||
@@ -241,7 +254,13 @@ function reconcileConstraints(model, constraints, base, junctionData, context) {
|
||||
?.some((item) => item.segmentId === constraint.anchor.segmentId),
|
||||
);
|
||||
}
|
||||
if (!matched) return { ...constraint, status: 'stale' };
|
||||
if (!matched) return { ...constraint, status: 'stale', replayReason: 'anchor-missing' };
|
||||
if ((versionChanged || context.replay) && constraint.kind === 'road-edge-offset') {
|
||||
const value = Number(constraint.value?.offsetMeters);
|
||||
const sides = constraint.anchor.side ? [constraint.anchor.side] : ['left', 'right'];
|
||||
if (sides.some((side) => !inRange(value, roadEdgeOffsetRange(model, { ...constraint.anchor, side }, null))))
|
||||
return { ...constraint, status: 'stale', replayReason: 'range-out-of-bounds' };
|
||||
}
|
||||
if (versionChanged) return { ...constraint, status: 'recheck' };
|
||||
return constraint;
|
||||
});
|
||||
@@ -253,6 +272,29 @@ function roadForAnchor(model, roadId) {
|
||||
);
|
||||
}
|
||||
|
||||
function inRange(value, range) {
|
||||
return Boolean(range && Number.isFinite(value) && value >= range.min && value <= range.max);
|
||||
}
|
||||
|
||||
// This is the authoritative range for both the published edge handle and the
|
||||
// solver. A segment can contain two directional roads, but an edge constraint
|
||||
// applies to exactly one `roadId`; using the segment total here was the source
|
||||
// of the previously advertised-but-invalid drag range.
|
||||
function roadEdgeOffsetRange(model, anchor, profile) {
|
||||
const road = roadForAnchor(model, anchor?.roadId);
|
||||
const side = anchor?.side;
|
||||
if (!road || !['left', 'right'].includes(side)) return null;
|
||||
const otherSide = side === 'left' ? 'right' : 'left';
|
||||
const otherOffset = Number(profile?.edgeOffsets?.[otherSide]) || 0;
|
||||
const width = Number(road.widthMeters);
|
||||
const minimumWidth = Number(road.laneCount) * MIN_LANE_WIDTH_METERS;
|
||||
if (!Number.isFinite(width) || !Number.isFinite(minimumWidth)) return null;
|
||||
return {
|
||||
min: Math.max(-width / 2, minimumWidth - width - otherOffset),
|
||||
max: width / 2,
|
||||
};
|
||||
}
|
||||
|
||||
function blocking(diagnostics, constraint, rule, message, coordinate = null) {
|
||||
diagnostics.push(diagnostic('error', `constraint:${constraint.id}`, [], rule, message, coordinate));
|
||||
}
|
||||
@@ -313,8 +355,15 @@ function applyRoadConstraint(model, constraint, profiles, diagnostics) {
|
||||
}
|
||||
if (constraint.kind === 'road-edge-offset') {
|
||||
const offset = Number(constraint.value?.offsetMeters);
|
||||
if (!Number.isFinite(offset)) {
|
||||
blocking(diagnostics, constraint, 'direct-edit-invalid-value', '外缘偏移必须是有限米数。');
|
||||
const ranges = sides.map((side) => roadEdgeOffsetRange(model, { ...anchor, side }, profile));
|
||||
if (ranges.some((range) => !inRange(offset, range))) {
|
||||
const range = ranges.find((item) => item && !inRange(offset, item)) || ranges[0];
|
||||
blocking(
|
||||
diagnostics,
|
||||
constraint,
|
||||
'direct-edit-edge-offset-out-of-range',
|
||||
`外缘偏移必须在 ${range ? `${range.min} 到 ${range.max}` : '当前道路可用范围'} 米之间。`,
|
||||
);
|
||||
return false;
|
||||
}
|
||||
for (const side of sides) {
|
||||
@@ -563,7 +612,7 @@ function roadAffects(roads, model, side, boundaryIndex) {
|
||||
return [...new Set(ids)];
|
||||
}
|
||||
|
||||
function makeRoadHandles(model, groups, reserves, constraints) {
|
||||
function makeRoadHandles(model, groups, reserves, constraints, roadProfiles) {
|
||||
const handles = [];
|
||||
for (const [segmentId, roads] of groups) {
|
||||
const road = roads.find((item) => item.direction === 'forward') || roads[0];
|
||||
@@ -621,12 +670,13 @@ function makeRoadHandles(model, groups, reserves, constraints) {
|
||||
const sideSign = side === 'left' ? -1 : 1;
|
||||
const edgeAnchor = { ...interval, side };
|
||||
const edgeConstraint = constraintFor(constraints, 'road-edge-offset', edgeAnchor);
|
||||
const edgeRange = roadEdgeOffsetRange(model, edgeAnchor, roadProfiles.get(road.id));
|
||||
add(
|
||||
'road-edge-offset',
|
||||
edgeAnchor,
|
||||
numericValue(edgeConstraint, 'offsetMeters', 0),
|
||||
-Math.max(0.1, width * 0.45),
|
||||
Math.max(0.1, width * 0.45),
|
||||
edgeRange.min,
|
||||
edgeRange.max,
|
||||
normal,
|
||||
offsetCoordinate(point, tangent + sideSign * 90, width / 2),
|
||||
roadAffects(roads, model, side),
|
||||
@@ -898,7 +948,7 @@ function resolveDirectEditConstraints(model, editDocument = null, context = {})
|
||||
handles.reserves = junctionData.reserves;
|
||||
handles.handles = selectHandles(
|
||||
[
|
||||
...makeRoadHandles(model || {}, groups, handles.reserves, reconciled),
|
||||
...makeRoadHandles(model || {}, groups, handles.reserves, reconciled, solved.roadProfiles),
|
||||
...makeJunctionHandles(model || {}, junctionData, reconciled),
|
||||
],
|
||||
model || {},
|
||||
@@ -928,5 +978,6 @@ module.exports = {
|
||||
SOLVED_KINDS,
|
||||
KINDS,
|
||||
GEOMETRY_VERSION,
|
||||
roadEdgeOffsetRange,
|
||||
resolveDirectEditConstraints,
|
||||
};
|
||||
@@ -184,6 +184,90 @@ const anchoredHandle = anchoredResolution.handles.handles.find(
|
||||
);
|
||||
assert.equal(anchoredHandle.constraintId, 'edge-on-road-a');
|
||||
|
||||
// The published edge extrema are solver extrema, not the segment's combined
|
||||
// directional width. Submitting either endpoint must be accepted by the same
|
||||
// resolver that published it.
|
||||
for (const side of ['left', 'right']) {
|
||||
const handle = junctionResolution.handles.handles.find(
|
||||
(item) => item.kind === 'road-edge-offset' && item.anchor.roadId === 'road:a' && item.anchor.side === side,
|
||||
);
|
||||
assert.ok(handle);
|
||||
const endpoint = resolveDirectEditConstraints(
|
||||
junctionModel,
|
||||
document([
|
||||
constraint({
|
||||
id: `edge-endpoint-${side}`,
|
||||
anchor: { ...handle.anchor },
|
||||
value: { offsetMeters: handle.value.min, transition: 'smoothstep' },
|
||||
}),
|
||||
]),
|
||||
);
|
||||
assert.equal(endpoint.constraintStates[0].applied, true, `${side} min must be solver-accepted`);
|
||||
assert.deepEqual(endpoint.diagnostics, []);
|
||||
const maxEndpoint = resolveDirectEditConstraints(
|
||||
junctionModel,
|
||||
document([
|
||||
constraint({
|
||||
id: `edge-endpoint-max-${side}`,
|
||||
anchor: { ...handle.anchor },
|
||||
value: { offsetMeters: handle.value.max, transition: 'smoothstep' },
|
||||
}),
|
||||
]),
|
||||
);
|
||||
assert.equal(maxEndpoint.constraintStates[0].applied, true, `${side} max must be solver-accepted`);
|
||||
assert.deepEqual(maxEndpoint.diagnostics, []);
|
||||
}
|
||||
|
||||
// A value that was legal on the original road becomes stale when a reimport
|
||||
// narrows that road's feasible range. It must not be replayed into geometry.
|
||||
const savedEdge = constraint({
|
||||
id: 'saved-edge',
|
||||
anchor: { type: 'road-interval', roadId: 'road:a', startStation: 0.2, endStation: 0.8, side: 'left' },
|
||||
value: { offsetMeters: 2.5, transition: 'smoothstep' },
|
||||
});
|
||||
const widenedModel = { ...junctionModel, roads: junctionModel.roads.map((road) => ({ ...road, widthMeters: 6 })) };
|
||||
const narrowedModel = { ...junctionModel, roads: junctionModel.roads.map((road) => ({ ...road, widthMeters: 4 })) };
|
||||
assert.equal(resolveDirectEditConstraints(widenedModel, document([savedEdge])).constraintStates[0].status, 'exact');
|
||||
const narrowed = resolveDirectEditConstraints(narrowedModel, document([savedEdge]), { replay: true });
|
||||
assert.deepEqual(narrowed.constraintStates[0], {
|
||||
constraintId: 'saved-edge',
|
||||
kind: 'road-edge-offset',
|
||||
status: 'stale',
|
||||
applied: false,
|
||||
reason: 'range-out-of-bounds',
|
||||
});
|
||||
assert.equal(narrowed.roadProfiles.size, 0);
|
||||
assert.deepEqual(narrowed.diagnostics, []);
|
||||
|
||||
// A new preview draft is invalid, not stale: the server must expose a blocking
|
||||
// diagnostic when a client bypasses the manifest and submits an out-of-range value.
|
||||
const previewInvalid = resolveDirectEditConstraints(
|
||||
junctionModel,
|
||||
document([
|
||||
constraint({
|
||||
id: 'preview-invalid-edge',
|
||||
anchor: savedEdge.anchor,
|
||||
value: { offsetMeters: 99, transition: 'smoothstep' },
|
||||
}),
|
||||
]),
|
||||
);
|
||||
assert.equal(previewInvalid.constraintStates[0].status, 'exact');
|
||||
assert.equal(previewInvalid.constraintStates[0].applied, false);
|
||||
assert.ok(previewInvalid.diagnostics.some((item) => item.rule === 'direct-edit-edge-offset-out-of-range'));
|
||||
|
||||
const bothEdges = resolveDirectEditConstraints(
|
||||
junctionModel,
|
||||
document([
|
||||
constraint({
|
||||
id: 'both-edges',
|
||||
anchor: { type: 'road-interval', roadId: 'road:a', startStation: 0.2, endStation: 0.8 },
|
||||
value: { offsetMeters: 0.5, transition: 'smoothstep' },
|
||||
}),
|
||||
]),
|
||||
);
|
||||
assert.equal(bothEdges.constraintStates[0].applied, true);
|
||||
assert.deepEqual(bothEdges.diagnostics, []);
|
||||
|
||||
const allKinds = [
|
||||
anchored,
|
||||
constraint({
|
||||
@@ -295,7 +379,7 @@ for (const status of ['exact', 'recheck']) {
|
||||
kind: 'road-edge-offset',
|
||||
status: 'stale',
|
||||
applied: false,
|
||||
reason: 'status-stale',
|
||||
reason: 'anchor-missing',
|
||||
},
|
||||
]);
|
||||
assert.deepEqual(resolution.diagnostics, []);
|
||||
|
||||
@@ -411,6 +411,7 @@ function rebaseEdits(area, revisionId) {
|
||||
const resolution = resolveDirectEditConstraints(model, revision.directEdits, {
|
||||
revisionId,
|
||||
compilerGeometryVersion: GEOMETRY_VERSION,
|
||||
replay: true,
|
||||
});
|
||||
const counts = Object.fromEntries(
|
||||
['exact', 'recheck', 'pending', 'conflicted', 'stale'].map((status) => [status, 0]),
|
||||
|
||||
Reference in new issue
Block a user