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,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` 通过。
## 关键决定
- 本轮严格保持已有功能、交互和视觉效果。每项迁移必须以现有行为为基线;发现未确认问题只记录,不随重构修改。