refactor(workbench): split editor state and components

This commit is contained in:
que01 committed 2026-09-02 15:04:58 +08:00
1 parent caa3cb843f
commit 834470cfa1
23 files changed
+1219 -878

No files matched your search

@@ -0,0 +1,74 @@
# 工作台组件边界重构设计
## 原则
这是一项严格的行为保持重构。API 调用顺序、保存语义、地图层、状态展示、文案和 DOM
结构在可观察层面保持不变;新模块只重新分配已有代码的所有权。
## 目标边界
```text
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 中。统一保存仍固定为:
```text
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 实例稳定性。