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

6.6 KiB
Raw Blame History

实施计划

顺序按风险递减排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。

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 开关行为与改动前一致。

验证命令

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,并验证选箭头、标线、信号、道路与连接的 现有保存流程未回归。