# 工作台组件边界重构设计 ## 原则 这是一项严格的行为保持重构。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 实例稳定性。