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,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 直写性能策略,只作为“道路”分段的内容,不被重写为另一条输入链路。