Files
road-compiler/.trellis/tasks/archive/2026-09/09-02-workbench-component-boundaries/design.md
T

3.9 KiB
Raw Blame History

工作台组件边界重构设计

原则

这是一项严格的行为保持重构。API 调用顺序、保存语义、地图层、状态展示、文案和 DOM 结构在可观察层面保持不变;新模块只重新分配已有代码的所有权。

目标边界

App
  ├─ 应用装载、页面布局、顶层命令
  ├─ useDirectEditSession
  │    └─ v2 EditSession / manifest / preview lifecycle
  ├─ useTrafficSignalDraft
  │    └─ signal local draft / undo-redo / move-rotate / save-discard
  ├─ WorkbenchInspector
  │    ├─ RoadOverrideForm
  │    ├─ LaneManeuverEditor
  │    ├─ MarkingEditor
  │    ├─ SignalEditor
  │    └─ CandidateList / technical details
  └─ MapCanvas
       └─ OpenLayers lifecycle and display-only interactions

App 保留跨域的组合责任:取得 WorkbenchState、挂接 map props、派发统一的“保存并重新生成”、 以及把各编辑域的状态/命令传给头部和右栏。它不再包含具体表单实现,也不内嵌某一编辑域的 预览或草稿算法。

状态所有权和数据流

域 唯一所有者 公开给 App 的内容 不可改变的规则
普通 v1 覆盖 useOverrideDraft staged, stage, save, discard 只经 /api/overrides 保存
v2 direct edit useDirectEditSession + App orchestration manifest、preview、session lifecycle; App retains gesture commands 只经 EditSession 与 preview API;lane-maneuver 只在此处
红绿灯 useTrafficSignalDraft dirty、move/rotate、undo/redo、save/discard、draftedState 本地草稿不提前写 API;保存时保持 40m 限制
选择与呈现 App selected road、element、marking、layers、scene MapCanvas 只接收 props,不能自行持久化编辑状态
右栏 WorkbenchInspector typed props 和局部折叠状态 不直接调用 API,不拥有跨域草稿

为避免在同一次渲染中存在两份 WorkbenchState,编辑 hooks 不复制整个状态;它们接收当前 state 和 setState,只将各自领域的不可序列化控制信息保留在 hook ref 中。统一保存仍固定为:

save normal overrides -> save v2 document (no compile) -> save signal draft -> compile -> replace state

迁移策略

  1. 先提取无状态右栏编辑器及其明确 props,保持 App 原有 state/command 实现不动。
  2. 提取普通 v1 覆盖草稿,并以现有保存/放弃逻辑测试锁定行为。
  3. 提取 v2 直接编辑协调 hook;保持 EditSession 的实例生命周期、PreviewRequester 的 previewSeq 仲裁和 ParameterPanel ref 入口不变。
  4. 提取红绿灯草稿 hook;移动、旋转和表单更新进入同一历史栈,保存仍由顶层统一编排。
  5. 最后删除 App 内的旧实现,验证每一个 map prop 与原来等价。

每一步单独可编译、可测试;不做“先复制全部再删除”的并行机制。若某 hook 提取导致行为难以 保持,则停在已有边界并记录原因,而不是创造新的共享全局状态。

兼容性和回滚

  • 不改动 src/、workbench/server.js 或任何请求/响应类型,导出包契约天然不受影响。
  • 不修改 MapCanvas 的建图 effect 依赖;其现有 refs 和临时图层保持所有权。
  • 每次迁移使用 Git 提交作为回滚点;回滚只移除新模块并恢复原调用点,不触及工作区数据。

规范更新

更新前端目录、组件、hook、状态和质量规范,写入以下可执行约束:

  • hook 只能拥有一个编辑域,跨域保存由 App 编排;
  • 组件通过 typed props 接受命令,不导入 API client 直接写入;
  • 不复制 WorkbenchState,不可序列化 session/history 仅在所属 hook ref;
  • MapCanvas 生命周期不得因 UI 抽取改变;
  • 重构 PR 必须覆盖保存顺序、discard/undo 和 map 实例稳定性。