chore(tasks): archive completed edit workflows

This commit is contained in:
que01 committed 2026-09-03 13:34:25 +08:00
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": {}
}
@@ -0,0 +1,4 @@
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"检查面板未写入 baseline source、控件值全部由 manifest 驱动、previewSeq 仲裁未被绕开。"}
{"file":".trellis/spec/frontend/state-management.md","reason":"检查聚焦/失焦的值所有权切换无第二真相来源,且中间态不被预览响应改写。"}
{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"检查新增纯逻辑的单测覆盖与客户端质量门槛。"}
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"核对拖拽与输入两条通道汇合于同一个 draftFor,未出现并行实现。"}
@@ -0,0 +1,138 @@
# 参数面板与数值双向绑定 · 设计
> 父任务 `08-26-direct-manipulation-road-editor/design.md` 仍是约束模型、求解边界与 API 合约的权威定义。本文只补充**第二条输入通道**引入的规则,不改变其中任何一条。
## 架构定位
本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层:
```text
┌─ 拖拽(连续)──→ projectHandleValue() ─┐
选中道路 → manifest ─┤ ├→ draftFor(handle, value)
└─ 输入框(离散)→ 解析 + 范围校验 ──────┘ ↓
PreviewRequester
(80ms 防抖 + previewSeq 仲裁)
↓
EditSession.commit()
```
`draftFor(handle, value)`(`App.tsx:206`)本就是纯函数 `(手柄, 数字) → 草稿`。两条通道的唯一区别是**如何产生那个数字**以及**何时闭合 gesture**,汇合点之后完全一致。
## 不变量:取值范围
> **约束值永不超出 manifest 声明的 `[min, max]`。**
>
> - **连续输入**(拖拽、滑杆)在极限处**停止移动**。ghost 与手柄按夹后的值绘制,绝不跟随越界的光标。
> - **离散输入**(数值框)**拒绝接受**越界值:标记非法、不发预览、不进 undo 栈、保留最后一个有效预览。范围提示可一键填入极值。
这是**一条规则的两种设备表达**,不是两套策略。
连续设备没有表达"拒绝"的手段——停止移动就是它的拒绝,而且是当场可见的:手柄停住、光标继续走。用户不会形成"我设成了 -24.1"这个信念。夹值理由见 `projection.ts:75` 的注释(ol-ext 探针把手柄拖到 -24.1m 而约束夹在 -5.4m,手柄指向一个不可能存在的路形)。
离散设备则相反:数字已经键入、Tab 已经按下,此时夹值是**事后篡改**。且失败模式不对称——
| 用户意图 | 夹值 | 拒绝 |
| --- | --- | --- |
| 打错(想输 2.4,输成 24) | 变成 5.4,看起来合理,可能永不被发现 | 立即可见 |
| 想拉满 | 如愿 | 多一步(或点范围提示一键填入) |
拒绝错了只损失一次击键;夹值错了会把一个**看起来正常的错误值**送进下游编译与仿真。故取拒绝。
## 值的所有权
任一时刻,一个参数的显示值来源是**唯一**且由聚焦状态决定的:
| 状态 | 显示值 | 理由 |
| --- | --- | --- |
| 未聚焦 | `handle.value.current` | 服务端权威回显 |
| 聚焦中 | 本地文本 draft | 保留 `1.`、`-`、空串等中间态 |
必须如此的原因:`App.tsx:197` 在每次预览结算时 `setManifest(response.handles)` 整体替换 manifest。受控输入若直接绑定 `value.current`,键入 `1.` 触发的防抖预览返回后会把输入框冲成 `1`,小数点消失。
失焦即清 draft。此时 `value.current` 必然等于刚提交的值——因为 `direct-edit-solver.js:136` 的 `numericValue()` 直接回显约束里的数字,服务端不改写。**故不存在"请求值 vs 求解值"的双显示需求。**
> 该结论依赖 solver 当前行为。若日后改为回写求解结果,本节规则失效,需同步重审。
## gesture 边界
`gestureIdentity()` 是懒创建的 operationId 单例,`commitGesture()` 释放它。它抽象的是"一段有始有终的操作",与指针无绑定关系,因此可原样承载键盘输入:
| 阶段 | 拖拽 | 输入框 | 动作 |
| --- | --- | --- | --- |
| 开始 | `pointerdown` | `focus` | 铸 operationId |
| 进行 | `pointermove` | `onChange` | `requester.schedule()`,**不 commit** |
| 结束 | `pointerup` | `blur` / `Enter` | `requester.flush()` + `commitGesture()` |
| 放弃 | — | `Escape` | 回滚显示值 + `requester.cancel()` |
`EditSession` 与 `gestureIdentity()` 无需改动。输入 `1.53` 产生一步 undo,而非四步。
滑杆(若实现)的 pointerdown/up 天然落在此表内,不引入新分支。
**保存路径**:`saveDirectEdits()` 必须在入口强制结算未闭合的 gesture。DOM 中 blur 先于 click 触发,直接点"保存"能赶上,但该顺序过于脆弱,不作为正确性依赖。
## 区间的单位分层
父 `design.md` 的坐标分层表规定持久化层只有米与归一化 station。显示层不受该表约束。
| 层 | 单位 |
| --- | --- |
| 持久化 / 传输 | `station` (0..1) |
| 面板显示与输入 | 米(`station × roadLengthMeters`) |
**只在用户实际编辑时换算**,不在每次渲染时做 米→station→米 的往返,否则四舍五入会让数字自行漂移。`roadLengthMeters` 取自 `IntervalRangeHandle`,与 range 手柄同源。
区间由整条道路共享(`rangeDraftFor` 重锚该路全部约束),故在面板中**每条路一行**,不随手柄重复。
## 面板可表达而拖拽不能表达的操作
`value.current` 在无约束时回落基线(外缘偏移基线为 0),因此"未修改"与"显式设为 0"数值完全相同。`handle.constraintId` 仅在约束存在时出现,客户端据此区分。
由此得到一个拖拽结构上无法提供的能力:**删除约束**。拖拽只能设值,不能移除。面板每行提供"重置",删除该约束并使该行回到未修改态。
这是参数面板的实质增量,而非拖拽的镜像显示。
## 渲染性能
`handleDragEvent` 每次 mousemove 触发,而 `App.tsx` 是单个 974 行组件。拖拽值回流面板必须经 rAF 节流,不得直接 `setState`。
节流有效性需在扩大面板规模前验证——手柄当前仅 5~6 个,问题不会自行显现。
## 边界
- 面板不得成为第二套几何算法或第二个值的真相来源。范围、位置、`affects`、可编辑性一律只来自服务端 manifest。
- 面板只呈现主地图拥有的 kind。路口 shape 三 kind 仍属 `JunctionTools`;保留区内手柄呈禁用态并显示 `disabledReason`。
- 不新增约束 kind,不改动求解器。
## 已知缺口
服务端 `applyConstraint` 只校验 `Number.isFinite` 与非负,**不校验 manifest 的 `min`/`max`**。今日范围仅由客户端 `projectHandleValue` 的夹值实际约束。
外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`),因此保存时合法的值可能在后续几何变化后越界。此类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
父 `design.md` 已为 `boundaryIndex` 定义同类规则——"重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射"——数值范围越界应同等处理。
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
## 右侧工作台信息架构(2026-09-01)
右栏是操作面板而非信息流。顶部固定呈现当前选择对象、其道路方向和修改状态;下方
采用单主展开区的手风琴,避免所有表单在初始状态占满地图旁的空间。
| 分段 | 内容 | 展开规则 | 写入语义 |
| --- | --- | --- | --- |
| 道路 | 基础道路覆盖、直接编辑参数 | 选中道路时默认展开 | override 暂存;直接编辑 preview/session |
| 元素 | 车道箭头、标线、信号灯 | 选择相应地图元素时自动展开 | 箭头/标线暂存;信号灯即时 API |
| 连接 | 路口连接、行驶动作、手工候选 | 默认收起 | override 暂存 |
| 高级 | 复杂路口候选、技术 JSON | 始终默认收起 | 候选沿用现有调用 |
每个分段使用受控 React 状态,而非依赖原生 `<details>` 的不可观察状态;这让地图选中
事件可以可靠地展开相应段,且移动端与桌面端保持同一状态模型。分段标题显示摘要
(如参数修改数、所选第几车道、连接数量),但不复制任何几何或约束值。
车道箭头在元素段显示 maneuver 选择、距路口端的米数读数和有限数值输入。数值输入与
拖曳都写同一 `lane-maneuver.placementDistanceMeters`;客户端只限制为有限非负值,控制
设施与端点安全位置仍由正式编译的 `nearestSafeTurnArrowPlacement()` 权威裁决。
为避免继续膨胀 `App.tsx`,右栏容器、对象摘要、手风琴、道路/连接/元素分段应迁入
`workbench/client/src/components/`。现有 `ParameterPanel` 保持其 manifest 值所有权和
DOM 直写性能策略,只作为“道路”分段的内容,不被重写为另一条输入链路。
@@ -0,0 +1,6 @@
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"面板是第二条输入通道,必须继续遵守 manifest 驱动、baseline 不被写入、预览时序与图层所有权。"}
{"file":".trellis/spec/frontend/state-management.md","reason":"聚焦期本地 draft 与服务端 value.current 的所有权切换是本任务的核心状态规则,不得产生第二个值的真相来源。"}
{"file":".trellis/spec/frontend/component-guidelines.md","reason":"新增参数面板组件需符合既有组件结构与职责边界。"}
{"file":".trellis/spec/frontend/hook-guidelines.md","reason":"拖拽回流的 rAF 节流以 hook 承载,需符合既有 hook 约定。"}
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"输入通道必须复用 draftFor / PreviewRequester / EditSession,禁止复制出第二套预览与 undo 链路。"}
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 约束模型、坐标分层、预览时序与 handle manifest 的权威合同。"}
@@ -0,0 +1,97 @@
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
## 0. 纯逻辑与测试夹具
- 在 `workbench/client/src/edit/` 新增参数值的纯逻辑:数值格式化/解析(保留 `1.`、`-`、空串中间态)、范围校验、`station ↔ 米` 换算。
- 与现有 `meters.ts` / `projection.ts` / `selection.ts` 同侧,**不得 import OpenLayers**。
- 失败优先的 vitest:越界判定的边界值、中间态解析不丢字符、米↔station 往返不漂移。
- 门禁:新增模块的单测在 node 下跑通,且 `grep -r "from 'ol" ` 对新文件无命中。
## 1. 面板只读渲染
- 新增面板组件,遍历 `editHandles` 渲染:中文名、`value.current`、单位、`[min, max]`。**此步不可编辑。**
- 多个 `road-lane-divider` 按 `boundaryIndex` 分行;不可编辑手柄呈禁用态并显示 `disabledReason`。
- 依 `handle.constraintId` 是否存在标记"已修改"。
- 区间每条路一行,以米显示。
- 验证:选中不同道路、选中含保留区的道路、选中多车道道路,面板结构正确。
- 门禁:`directEdit` 开关关闭时面板不渲染、不请求 manifest,网络轨迹与 main 一致。
## 2. 拖拽 → 面板回流
- 拖拽值**直接写 DOM 节点**(ref + `textContent` / `value`),不经 React 渲染。
`direct-edit-client.md` §7:rAF 合并是**最低要求**,"写到源头"才是生产规则;ghost 直接写 OL source,面板的等价物是直接写 DOM。
- **禁止**在 `handleDragEvent` 中 `setState`;gesture 结束时才做一次 state 对账。
- 禁止在 `setState` updater 内计算或读 OL 状态(§6)。
- 验证:拖拽过程中面板数值实时跟随;用 render 计数确认**面板未新增任何渲染**。
注意门禁不是"拖拽期间渲染 0 次"——`onSettled` 的 `setManifest` 本就会在拖拽中随防抖预览触发渲染,那是服务端权威预览的固有代价,改动前就存在。要证明的是 `pointermove` 自身不再产生渲染。
- 拖拽中落地的预览会把 manifest 换成滞后一个防抖周期的值,需保证数字不在两者间闪烁。
- 门禁:节流有效性必须在此步证明。手柄当前仅 5~6 个,问题不会自行显现;跳过则后续无从归因。
## 3. 输入通道:预览、gesture 边界、commit
- 输入框接入 `draftFor` → `PreviewRequester.schedule()`,复用 80ms 防抖与 `previewSeq` 仲裁。
- gesture 边界按 `design.md` 表实现:`focus` 铸 operationId,`onChange` 只预览,`blur` / `Enter` 走 `flush()` + `commitGesture()`,`Escape` 回滚 + `cancel()`。
- 聚焦期间显示本地文本 draft,失焦后跟随 `value.current`。
- **`EditSession` 与 `gestureIdentity()` 不得修改**;若发现需要改,说明边界映射错了,退回重审。
- 验证:输入框改值与拖到同一数值产出同形约束;输入 `1.53` 后一次 Ctrl+Z 回到修改前;键入 `1.` 期间到达的预览响应不改写输入框。
- 门禁:一次非空表单编辑可在正式重编译结果中观察到几何变化。只交付 UI 不算通过。
## 4. 范围拒绝与极值填入
- 越界输入:标红、**不发预览请求**、不进 undo 栈、保留最后一个有效预览。
- 拖拽与滑杆的夹值行为保持不变(`projectHandleValue` 不改)。
- 范围提示中的极值可点击填入。
- 验证:越界时网络面板无新请求;blur 后无新 undo 步骤;点击极值可正常提交;拖拽越界时手柄仍停在极限。
- 门禁:夹值与拒绝的差异必须体现为 `design.md` 中的同一条不变量,不得实现成两条并列策略。
## 5. 重置与区间换算
- 每行"重置"删除该约束,使该行回到未修改态(`constraintId` 消失、值回落基线)。
- 区间的米↔station 换算实现并单测;**区间行受 `intervalEditingSupported` 门控,当前为 `false` 故不渲染**。
理由与 range 手柄一致(`flag.ts:46`):`compileGeometry()` 不读 `profile.interval`,一个改了没效果的输入框比没有更糟。
换算只在用户实际编辑时进行,渲染路径不做米→station→米 往返。
- 验证:重置后保存重编译,该参数回到基线;换算函数往返无累积漂移;开关为 `false` 时面板不出现区间行。
## 6. 加固与手测
- `saveDirectEdits()` 入口强制结算未闭合 gesture,不依赖 blur/click 顺序。
- 手测清单:
- 输入未失焦直接点"保存",修改被正确持久化。
- 拖拽与输入交替操作,undo/redo 序列正确。
- 快速连续输入,乱序预览响应不覆盖较新结果。
- 切换选中道路时未闭合的输入被正确结算或放弃。
- OpenLayers `Map` 未被重建,仅受影响 source 被替换。
- 门禁:交付前 `directEdit` 开关行为与改动前一致。
## 验证命令
```sh
npm run format:check
npm run test
npm run test:client
npm run test:client:unit
npm run build
```
## 风险文件
- `workbench/client/src/App.tsx`:974 行单组件。面板 state 与拖拽回流都落在此处,是重渲染风险的集中点;必要时先抽出编辑状态再加面板。
- `workbench/client/src/edit/session.ts`:**不应修改**。若实现中需要改动,说明 gesture 边界映射有误。
- `workbench/client/src/edit/projection.ts`:`projectHandleValue` 的夹值是拖拽正确性的一部分(见其 75 行注释),不得为"统一行为"而移除。
- `workbench/client/src/edit/preview-request.ts`:防抖与 `previewSeq` 仲裁由两条通道共用,任何改动同时影响拖拽。
- `src/compile/direct-edit-solver.js`:**本任务不改**。若发现必须改,先确认不是把服务端校验缺口混进了本任务范围。
## 右侧工作台扩展(2026-09-01)
1. 抽出受控手风琴和选择对象摘要组件,建立“道路 / 元素 / 连接 / 高级”四段及其
自动展开规则;先用静态现有内容验证不改变写入行为。
2. 将现有 `Inspector` 的道路覆盖、连接、候选和技术详情迁入对应分段;将标线、箭头、
信号迁入元素分段。保留 `ParameterPanel` 的 API 和直接编辑数据流。
3. 补充箭头位置的米数读数和精确输入,与拖曳使用同一 staged override;输入非法值不暂存。
4. 用组件/纯逻辑单测覆盖自动展开、分段摘要、箭头位置写入和不同写入语义;手测桌面及
窄屏的空间、焦点和滚动。
5. 执行 `npm run format:check`、`npm run test`、`npm run test:client`、
`npm run test:client:unit`、`npm run build`,并验证选箭头、标线、信号、道路与连接的
现有保存流程未回归。
@@ -0,0 +1,118 @@
# 参数面板与数值双向绑定
## 目标
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
## 已确认的事实
以下均为读代码核实,不是推断:
- `App.tsx:206` 的 `draftFor(handle, value)` 已经是纯函数 `(手柄, 数字) → 草稿`。拖拽只是产生这个数字的一种方式;输入框可以复用同一个入口。
- `EditHandle.value` 是 `{ current, min, max, unit: 'meter' }`——**取值范围服务端早已下发**,客户端不需要新增来源。
- `direct-edit-solver.js:136` 的 `numericValue(constraint, key, fallback)` 直接从约束读值,无约束时回落基线。**服务端从不改写用户输入的数字**;值非法时发阻塞诊断(`direct-edit-invalid-value`)拒绝,不做静默替换。因此不存在"请求值 vs 求解值"两个数字。
- `App.tsx:197` 每次预览结算都 `setManifest(response.handles)` 整体替换 manifest,`value.current` 随之刷新。受控输入若直接绑定它,输入中间态(`1.`、`-`、空串)会被冲掉。
- `projection.ts:60` 的 `projectHandleValue` 把拖拽值夹到 `[min, max]`,`ghost.show()` 与 `handlePositionFor()` 都按夹后的值绘制。拖拽越界时手柄停在极限、光标继续移动。
- 服务端 `applyConstraint`(`direct-edit-solver.js:302/312/322` 附近)只校验 `Number.isFinite` 与非负,**未校验 manifest 的 `min`/`max`**。范围目前是纯客户端概念。
- 外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`);步行带固定 `0..8`;角部圆角固定 `0.5..30`。
- `gestureIdentity()` 懒创建 operationId,`commitGesture()` 释放它。一次 gesture = `EditSession.commit()` 一次 = 一步 undo。该机制与指针无绑定关系。
- `handle.constraintId` 仅在约束存在时出现,因此客户端能区分"未修改(基线回落)"与"显式设为该值"。
- 区间由整条道路共享:`rangeDraftFor` 会把该路上所有约束一起重锚。`IntervalRangeHandle` 同时携带 `station` 与 `roadLengthMeters`。
- 同一条路可有多个 `road-lane-divider` 手柄,靠 `boundaryIndex` 区分。
- `direct-edit-solver.js` 写 `profile.interval`(290、472 行),但 `compileGeometry()` 不读它——`native-road.js` 中 `interval` 的唯一命中是方向箭头间距,与此无关。**每次直接编辑实际作用于整条道路。** 因此 `flag.ts:46` 的 `intervalEditingSupported` 为 `false`,range 手柄被隐藏。
- 当前**没有任何参数面板**。与手柄相关的 UI 仅 `App.tsx:404` 状态栏一句 `手柄 ${n} 个`。
- `handleDragEvent` 每次 mousemove 触发;`App.tsx` 是单个 974 行组件。
## 范围
### 1. 面板与读取
1. 选中道路后,面板按手柄列出可编辑参数:中文名、当前值、单位、合法范围。
2. 多个 `road-lane-divider` 分别成行,用 `boundaryIndex` 标识,不按 kind 去重。
3. 影响区间**每条路一行**(不是每个手柄一行),以米显示,`station` 仍是唯一存储真相。
**受 `intervalEditingSupported` 门控**:该开关当前为 `false`,故本任务不渲染区间行。
换算与显示逻辑仍按第 5 节实现并单测,随开关翻转一并生效。
4. 每行标记该参数是否已被显式修改(依据 `handle.constraintId` 是否存在)。
5. 不可编辑手柄(落在路口保留区)在面板中呈禁用态并显示 `disabledReason`。
### 2. 拖拽 → 数字
6. 拖拽过程中面板数值实时跟随,与地图 ghost 同步。
7. 高频更新经 rAF 节流,不得每次 mousemove 触发整个 App 重渲染。
### 3. 数字 → 图形
8. 输入框修改值时走与拖拽相同的 `draftFor` → `PreviewRequester` 链路,含 80ms 防抖与 `previewSeq` 仲裁。
9. gesture 边界:`focus` 对应 `pointerdown`(铸 operationId),`blur` / `Enter` 对应 `pointerup`(`commitGesture`)。输入 `1.53` 只产生**一步** undo。
10. `Escape` 回滚到上一个有效值并 `cancel()` 在途请求。
11. 聚焦期间输入框显示本地文本,失焦后跟随 `value.current`。中间态不被预览响应冲掉。
12. `saveDirectEdits()` 入口先强制结算未闭合的 gesture,不依赖 blur 与 click 的触发顺序。
### 4. 范围处理
13. 拖拽与滑杆维持夹值(`projectHandleValue` 不变)。
14. 数值输入**不夹值**:越界时标记非法、不发预览、不进 undo 栈,保留最后一个有效预览。
15. 范围提示中的极值可一键填入。
### 5. 重置
16. 每行提供"重置",删除该约束回到基线。这是拖拽无法表达的操作——拖拽只能设值,不能移除约束。
## 明确不做
- 不移除、不削弱地图上的拖拽手柄。
- 不新增约束 kind,不改动求解器几何逻辑。
- 不补服务端 `min`/`max` 校验(见「已知缺口」,另立任务)。
- 不做参数的批量编辑、复制粘贴、跨道路应用。
- 不动 `JunctionTools` 的所有权边界;面板只呈现主地图拥有的 kind。
- 不同步遗留 `workbench/client/app.js`。
## 验收标准
- [ ] 选中道路后面板列出全部可编辑参数;多条车道分隔各自成行且可独立修改。
- [ ] 拖拽手柄时面板数值实时跟随;拖拽期间 React 重渲染次数经 rAF 收敛(非每 mousemove 一次)。
- [ ] 输入框改值后地图预览更新,与拖到同一数值的结果一致。
- [ ] 输入 `1.53` 后按 Ctrl+Z **一次**即回到修改前状态。
- [ ] 输入过程中(如已键入 `1.`)到达的预览响应不会改写输入框内容。
- [ ] 输入越界值:字段标红、不发预览请求(可由网络面板证明)、保留上一个有效预览、blur 后不产生 undo 步骤。
- [ ] 点击范围提示中的极值可一键填入并正常提交。
- [ ] 拖拽越界时手柄停在极限位置,行为与改动前一致。
- [ ] 未修改参数与显式设为基线值的参数在面板上可区分;"重置"能删除约束并使该行回到未修改态。
- [ ] 影响区间的米↔station 换算函数经单测覆盖,往返无累积漂移。(区间行本身受 `intervalEditingSupported` 门控,当前不渲染。)
- [ ] 输入未失焦时直接点"保存",该次修改被正确持久化。
- [ ] 路口保留区内的手柄在面板中禁用并显示原因。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
## 风险与门槛
- 面板不得成为第二套几何或第二个值的真相来源。所有范围、位置、影响对象仍只来自服务端 manifest。
- `value.current` 是**请求值的回显**而非求解值。若后续 solver 改成回写求解结果,第 11 条的显示规则失效,必须同步重审。
- 外缘偏移的 `min`/`max` 随道路宽度浮动,因此"当前合法"不等于"永远合法"。客户端校验只能覆盖输入当下。
- 拖拽回流若实现为直接 `setState`,会逐帧重渲染 974 行的 `App`。必须先确认节流有效再扩大面板规模。
## 已知缺口(不在本任务内)
服务端只校验 finite/非负,不校验 manifest 的 `min`/`max`;而外缘偏移范围随道路宽度浮动,意味着保存时合法的值可能在几何变化后越界。这类越界**客户端结构上无法拦截**——它发生在保存之后的求解期。
`design.md` 已为 `boundaryIndex` 定义了同类规则("重放时若车道数变化导致越界,该约束转 `stale`"),数值范围越界应当同等处理。属重放正确性,独立成任务。
## 右侧工作台扩展(2026-09-01)
当前右侧栏将道路基础覆盖、直接编辑参数、路口连接、车道转向箭头、标线样式、
原生信号灯、复杂路口候选和技术 JSON 直接按顺序堆叠,缺少所选对象摘要、明确的
编辑上下文和一致的表单层级。用户确认本轮应覆盖全部既有编辑器,而非只处理道路
参数或车道箭头。
拟纳入范围:
- 统一右侧栏的对象摘要、未保存/即时保存状态和表单布局。
- 重新组织道路、元素、连接、调试/技术详情中的全部既有表单与信息展示。
- 为车道转向箭头补足距路口位置的可读数与精确输入,继续复用
`placementDistanceMeters` 覆盖和既有拖曳行为。
- 保持各写入语义:普通 override 继续暂存并经保存/重新生成生效;信号灯继续走
现有即时 API;直接编辑继续走 manifest/preview/session 链路。
已决 UX:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。
所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。
@@ -0,0 +1,108 @@
# manifest 范围与求解器可行域不一致
日期:2026-08-31
来源:`08-31-parameter-panel-binding` 实施期间对运行中工作台(`osm-KZZP9U`)的实测。
## 现象
手柄 `handle:road-edge-offset:segment:way/-3246/0:left`,manifest 声明
`value.min = -2.925`、`value.max = 2.925`(即 `±width * 0.45`,道路宽 6.5m)。
逐值探测 `POST /api/edit-preview`:
| offsetMeters | 阻塞诊断 |
| --- | --- |
| -2.90 | `direct-edit-outer-edges-cross` |
| -2.00 | `direct-edit-outer-edges-cross` |
| -1.00 | `direct-edit-outer-edges-cross` |
| **-0.50** | **(无)** |
| **0.00** | **(无)** |
| **0.50** | **(无)** |
| **1.00** | **(无)** |
| 2.00 | `direct-edit-outer-edges-cross` |
| 2.90 | `direct-edit-outer-edges-cross` |
| 500 | `direct-edit-outer-edges-cross` |
探针构造已排除误报:小幅值干净,说明请求本身合法。
## 结论
**manifest 宣告的范围比求解器实际接受的可行域宽约 3 倍,且双向都是。**
真实边界落在 `(-1.0, -0.5]` 与 `[1.0, 2.0)` 之间,未进一步二分。
失败原因未查明。`direct-edit-outer-edges-cross` 对应 design.md 的
「同一站点左右外缘不得交叉」不变量,但仅移动**单侧**外缘 1m
(6.5m 宽的路)为何会触发交叉,需要读 `compileGeometry()` 才能确定——
可能经由车道最小宽度 2.4m 派生,也可能诊断名不完全对应其实际判据。
## 与既有行为的关系
这不是本任务引入的。拖拽一直夹到 `±2.925`,所以用户一直能拖进被拒区间——
拖过约 1m 后几何冻结、诊断出现,而手柄继续走到 2.925。
按 design.md「无效草稿不替换最后一个有效预览」,这是既定行为。
参数面板没有改变它,但**把它变可见了**:范围以文字打印,且极值可一键填入。
点击极值会得到一个必被服务端拒绝的值。
## 处理
未在本任务修改。理由:
- 客户端范围校验必须用 manifest 的 `min`/`max`,用别的就是发明第二个真相来源
(`direct-edit-client.md` §2)。
- 收窄范围需要求解器解析地算出外缘交叉的可行区间,属求解器工作,
本任务明确排除。
- 点击极值的结果是一个诚实的服务端拒绝:诊断可见、最后一个有效预览保留、可撤销。
不是静默破坏。
已并入 `08-31-constraint-range-validation` 的需求。
---
# 追加:`junction-crosswalk-inset` 的静默死区
日期:2026-08-31,区域 `nantaizihu-9PTsZg`。
手柄 `handle:junction-crosswalk-inset:node/1140799725:segment:way/-3246/0`
声明 `value.min = 0`、`value.max = 8`。逐值提交预览并测量该组 6 条斑马线的中心位移:
| inset | 相对 inset=0 的位移 | 增量 |
| --- | --- | --- |
| 0 | 0.00 | — |
| 0.5 | 0.50 | +0.50 |
| 1.0 | 1.00 | +0.50 |
| 2.0 | 2.00 | +0.50 |
| 3.0 | 3.00 | +0.50 |
| 4.0 | 3.20 | +0.20 |
| 5.0 | 3.20 | **+0.00** |
| 6.0 | 3.20 | **+0.00** |
| 8.0 | 3.20 | **+0.00** |
`0 → 3.2` 是干净的 1:1 线性响应;`3.2 → 8` **完全无响应,且无任何诊断**。
## 成因
`crossingJunctionInset()`(`native-road.js:1325`):
```js
const targetDistance = Math.max(0, plan.cutbackMeters - inset);
return Math.min(CROSSWALK_MAX_JUNCTION_INSET_METERS,
Math.max(0, candidate.junctionDistanceMeters - targetDistance));
```
inset 增至 `plan.cutbackMeters` 后 `targetDistance` 触底为 0,再增无效;
外层 `CROSSWALK_MAX_JUNCTION_INSET_METERS = 4` 另有封顶。
因此有效上界是 `min(cutbackMeters, …)` 的某个函数,**逐进口不同**,
而 manifest 对所有进口一律发布固定的 `max: 8`。
## 为何比外缘偏移那例更严重
外缘偏移越界会返回阻塞诊断——用户看得到"不行"。
本例越界**什么都不发生**:拖动手柄,几何纹丝不动,没有诊断、没有提示。
与「控件坏了」无法区分。
这正是 `flag.ts` 为 `profile.interval` 立下的规矩所要避免的
(「一个拖了没效果的控件比没有控件更糟」),区别只在于它发生在量程的上半段,
而不是整个控件。
若用户在已处于死区的进口上首次尝试拖拽,得到的印象就是"直接编辑不工作"。
@@ -0,0 +1,26 @@
{
"id": "parameter-panel-binding",
"name": "parameter-panel-binding",
"title": "参数面板与数值双向绑定",
"description": "为直接编辑加参数面板:数值输入与地图拖拽双向绑定,共用同一条约束/预览/undo 链路",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"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": {}
}