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

3.4 KiB

前端工作台组件边界重构

目标

在继续增加地图编辑能力前,将 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 通过。

关键决定

  • 本轮严格保持已有功能、交互和视觉效果。每项迁移必须以现有行为为基线;发现未确认问题只记录,不随重构修改。