Files
road-compiler/.trellis/tasks/08-31-parameter-panel-binding/implement.md
T

98 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
## 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`,并验证选箭头、标线、信号、道路与连接的
现有保存流程未回归。