3.9 KiB
3.9 KiB
工作台组件边界重构设计
原则
这是一项严格的行为保持重构。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
迁移策略
- 先提取无状态右栏编辑器及其明确 props,保持
App原有 state/command 实现不动。 - 提取普通 v1 覆盖草稿,并以现有保存/放弃逻辑测试锁定行为。
- 提取 v2 直接编辑协调 hook;保持
EditSession的实例生命周期、PreviewRequester的 previewSeq 仲裁和ParameterPanelref 入口不变。 - 提取红绿灯草稿 hook;移动、旋转和表单更新进入同一历史栈,保存仍由顶层统一编排。
- 最后删除 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 实例稳定性。