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,2 @@
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"The direct-edit contract defines lane-maneuver ownership and preview/session invariants used by this refactor."}
{"file":".trellis/spec/frontend/state-management.md","reason":"The state ownership and fixed save order govern the extracted hooks and App composition."}
@@ -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 实例稳定性。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,29 @@
# 实施计划
1. 建立组件与 hook 的类型边界,提取右栏编辑器和 `WorkbenchInspector`;逐项比对现有 props、
文案和折叠默认状态。
2. 提取 `useOverrideDraft`,为 staged 合并、覆盖保存和放弃建立纯函数或聚焦测试。
3. 提取 `useDirectEditSession`,集中拥有现有 `EditSession`、manifest、preview 和 diagnostics
生命周期;手柄/lane 派生、undo/redo 与统一保存入口仍由 App 编排,以避免改变预览时序。
4. 提取 `useTrafficSignalDraft`,收拢 signal 草稿、移动、旋转、撤销/重做、放弃和保存;复用现有
距离限制与 heading 派生,不重写几何算法。
5. 将 App 缩至页面编排与命令组合,运行 map 交互回归;删除不再使用的内嵌实现。
6. 更新 `.trellis/spec/frontend/`:`directory-structure.md`、`component-guidelines.md`、
`hook-guidelines.md`、`state-management.md`、`quality-guidelines.md`。
7. 运行格式、完整服务器测试、客户端类型/单测、生产构建和 diff 检查;人工核验保存/放弃/撤销及
地图视角稳定性。
## 验证命令
- `npm run format:check`
- `npm run test`
- `npm run test:client`
- `npm run test:client:unit -- --run`
- `npm run build`
- `git diff --check`
## 高风险点
- `EditSession` 和 `PreviewRequester` 依赖稳定对象身份;提取时不可在每次渲染重建。
- 红绿灯草稿与 v2 document 都参与顶部撤销/放弃命令;优先级与现有分支必须保持。
- `MapCanvas` 的 OpenLayers effect 必须仍只在 mount 时建图,不能让 hook 或 inspector props 触发重建。
@@ -0,0 +1,49 @@
# 前端工作台组件边界重构
## 目标
在继续增加地图编辑能力前,将 React 工作台从单个过大的 `App.tsx` 中拆出清晰、可测的
应用编排、编辑状态、地图选择和右侧检查器边界。重构后继续沿用现有工作流,而非借重构
改变已确认的编辑行为。
## 已确认事实
- `workbench/client/src/App.tsx` 为 1,684 行,既装载 API 状态,又维护普通 v1 staged override、
v2 `EditSession`/preview、红绿灯本地草稿历史、地图选择、页面命令和右侧表单。导向箭头
`lane-maneuver` 已只走 v2,不属于 v1 staged。
- `MapCanvas.tsx` 已拥有 OpenLayers 生命周期与临时地图叠加层;`ParameterPanel.tsx` 已拥有
参数输入文本与 DOM 级实时显示;`InspectorSection.tsx` 已拥有受控手风琴段落。
- 右栏内嵌的 `Inspector`、`LaneManeuverEditor`、`MarkingEditor`、`SignalEditor`、`Candidates`
不可独立复用或单测,且其依赖由 `App.tsx` 的闭包隐式提供。
- 当前保存语义不可改变:普通 v1 覆盖(道路、连接、标线样式)暂存;v2 直接编辑(含
`lane-maneuver`)经 session/preview/document;红绿灯
通过本地草稿、独立撤销栈和信号 API;“保存并重新生成”按既有顺序保存三者后正式编译。
- `MapCanvas` 必须只构造一次,不能因 React 组件拆分或状态变更重新初始化地图。
## 范围
1. 将应用数据装载、工作台编辑协调、选择/图层展示、右侧检查器表单划分为具名模块或 hooks。
2. 将右栏编辑器从 `App.tsx` 迁入 `components/`,通过明确的 typed props 传入状态和命令。
3. 抽出直接编辑和红绿灯草稿生命周期的状态所有权,避免页面组件同时维护多组可变 refs。
4. 为新增边界补充前端规范:目录职责、hook 规则、状态所有权、组件 props 和回归验证要求。
5. 为关键纯派生与保存顺序补充聚焦测试;保留现有 API 和导出包契约。
## 非范围
- 不新增或删除地图编辑能力,不改变红绿灯、斑马线、导向箭头的交互。
- 不修改服务端 API、导出包字段、v1/v2 文档协议或编译器。
- 不在本任务重新设计右侧视觉样式、引入新的 UI 库,或处理未实现的旋转/新元素功能。
- 不顺手修复任何尚未由用户确认的 UI 或交互问题;这类问题另立任务处理。
## 验收标准
- [ ] `App.tsx` 只保留页面组合、顶层状态连接和明确的命令入口,不再内嵌右栏编辑器或大段编辑会话实现。
- [ ] 每个 extracted component/hook 有单一所有权,props 和返回值均为显式 TypeScript 合约;没有通过 module mutable state 或 DOM 查询传递业务数据。
- [ ] 普通 v1 staged、v2 direct-edit(含 `lane-maneuver`)、traffic-signal 三条编辑/撤销/放弃/保存并重新生成流程与重构前一致。
- [ ] 地图在选择、保存、放弃、撤销与右栏重渲染时不被重新创建,也不丢失视角。
- [ ] 选中元素仍自动展开对应右栏段;取消选择仍清理临时元素/红绿灯操纵控件。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit -- --run`、`npm run build` 通过。
## 关键决定
- 本轮严格保持已有功能、交互和视觉效果。每项迁移必须以现有行为为基线;发现未确认问题只记录,不随重构修改。
@@ -0,0 +1,26 @@
{
"id": "workbench-component-boundaries",
"name": "workbench-component-boundaries",
"title": "前端工作台组件边界重构",
"description": "拆分 App.tsx 的应用编排、编辑状态和右侧检查器,建立可执行前端 React 组件边界规范。",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": "2026-09-02",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
"meta": {}
}