3.3 KiB
3.3 KiB
迁移工作台到 React 前端
Goal
将现有原生 HTML/CSS/JS 工作台迁移到 Vite、React 19、TypeScript 和 shadcn/ui，获得可维护、可扩展且具备类型安全的成熟前端工程结构，同时保留当前 OSM 导入、地图查看、道路参数编辑、诊断、信号灯编辑、重新编译和道路包导出能力。
Confirmed Facts
- 当前前端位于
workbench/client/index.html、workbench/client/app.js和workbench/client/app.css。 workbench/client/app.js使用 OpenLayers 浏览器模块，并动态创建部分控制面板和图层开关。workbench/server.js提供静态资源和/api/state、/api/import、/api/overrides、/api/traffic-signals、/api/compile、/api/export.zip等接口。- 当前项目是 CommonJS Node 包，尚无前端构建脚本、TypeScript 配置、Vite 配置或 shadcn/ui 依赖。
- 地图核心继续使用已有的 OpenLayers 10；本任务是前端工程迁移，不替换地图引擎。
Requirements
- 建立独立、可构建的 Vite React 19 TypeScript 前端入口并迁移工作台代码。
- 配置 shadcn/ui 所需的 CSS 变量、组件基础设施和图标/交互约定，优先使用其组件承载按钮、表单、面板、弹层和提示。
- 将页面状态、API 调用、地图图层/选择逻辑和编辑表单拆分为 React 组件、hooks、类型和服务模块，避免主要业务 UI 继续依赖全局
querySelector和动态innerHTML。 - 保留现有服务端 API 契约和 OSM 导入工作流；必要时只调整静态资源托管和开发/生产构建入口。
- 保留 OpenLayers 地图的现有图层、样式、选择和交互行为，并确保状态变化正确驱动地图与检查器更新。
- 提供开发模式和生产构建命令；Node 工作台服务能提供构建后的前端资源。
- 为核心 API 客户端、状态转换和至少一个关键交互增加 TypeScript/自动化验证。
Acceptance Criteria
npm run build能在干净依赖安装后生成前端生产构建产物。npm run dev（或等价命令）能启动 Vite 开发服务器并加载工作台页面。npm run road:workbench使用构建产物时仍能打开工作台；无活动工作区时显示 OSM 导入界面，有活动工作区时显示地图和编辑器。- OSM 导入、图层开关、道路选择/参数暂存、诊断筛选、交通信号编辑、保存、重新编译和 ZIP 导出均保持可用。
- 页面不再通过原生
querySelector/innerHTML组织主要业务 UI；业务状态和 API 数据具有明确 TypeScript 类型。 - 现有 Node 编译器测试继续通过；新增前端构建和关键工作流验证通过。
Out Of Scope
- 不修改道路编译算法、OSM 解析规则、GeoJSON 数据结构或现有 HTTP API 语义。
- 不更换 OpenLayers 为其他地图引擎。
- 不引入认证、多用户协作、服务端渲染或远程部署平台。
- 不在本任务内重新定义道路参数模型或增加新的业务功能。
Open Product Decision
迁移是否同时允许明显的视觉和信息架构重设计？推荐第一阶段以“功能和工作流等价 + shadcn/ui 统一视觉”为目标，保留现有三栏地图工作台布局；这样可以把风险集中在工程迁移，后续再单独做 UX 重构。若本任务同时重做布局，交付周期和回归范围会显著增加。