diff --git a/.trellis/spec/backend/direct-edit-api.md b/.trellis/spec/backend/direct-edit-api.md index 94d3fb0..7ea321c 100644 --- a/.trellis/spec/backend/direct-edit-api.md +++ b/.trellis/spec/backend/direct-edit-api.md @@ -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 diff --git a/.trellis/tasks/08-31-constraint-range-validation/design.md b/.trellis/tasks/08-31-constraint-range-validation/design.md new file mode 100644 index 0000000..2f67b9c --- /dev/null +++ b/.trellis/tasks/08-31-constraint-range-validation/design.md @@ -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 拒绝,不能把其他约束偷偷改掉。 diff --git a/.trellis/tasks/08-31-constraint-range-validation/implement.md b/.trellis/tasks/08-31-constraint-range-validation/implement.md new file mode 100644 index 0000000..1cfc5cc --- /dev/null +++ b/.trellis/tasks/08-31-constraint-range-validation/implement.md @@ -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 不受影响。 diff --git a/.trellis/tasks/08-31-constraint-range-validation/task.json b/.trellis/tasks/08-31-constraint-range-validation/task.json index 463b361..8a819d9 100644 --- a/.trellis/tasks/08-31-constraint-range-validation/task.json +++ b/.trellis/tasks/08-31-constraint-range-validation/task.json @@ -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, diff --git a/src/compile/direct-edit-solver.js b/src/compile/direct-edit-solver.js index 82b9e1e..c01b0ae 100644 --- a/src/compile/direct-edit-solver.js +++ b/src/compile/direct-edit-solver.js @@ -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, }; diff --git a/test/direct-edit-solver.js b/test/direct-edit-solver.js index ac1b39e..7ff2bc5 100644 --- a/test/direct-edit-solver.js +++ b/test/direct-edit-solver.js @@ -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, []); diff --git a/workbench/server.js b/workbench/server.js index 937b1c4..7d2c3e0 100644 --- a/workbench/server.js +++ b/workbench/server.js @@ -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]),