chore(tasks): archive completed edit workflows
This commit is contained in:
1 parent
a78f5257fc
commit
39d7453ebc
13 files changed
+4
-4
No files matched your search
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -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 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -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 不受影响。
|
||||
@@ -0,0 +1,70 @@
|
||||
# 约束值范围的服务端校验与重放失效
|
||||
|
||||
## 目标
|
||||
|
||||
让 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` 的「已知缺口」。
|
||||
- 本任务不阻塞面板任务:面板的客户端校验独立成立。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "constraint-range-validation",
|
||||
"name": "constraint-range-validation",
|
||||
"title": "约束值范围的服务端校验与重放失效",
|
||||
"description": "服务端补 manifest min/max 校验;保存后因几何变化导致的数值越界转 stale",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P3",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-31",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in new issue
Block a user