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

75 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 工作台组件边界重构设计
## 原则
这是一项严格的行为保持重构。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 实例稳定性。