44 lines
3.3 KiB
Markdown
44 lines
3.3 KiB
Markdown
# 迁移工作台到 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
|
||
|
||
1. 建立独立、可构建的 Vite React 19 TypeScript 前端入口并迁移工作台代码。
|
||
2. 配置 shadcn/ui 所需的 CSS 变量、组件基础设施和图标/交互约定，优先使用其组件承载按钮、表单、面板、弹层和提示。
|
||
3. 将页面状态、API 调用、地图图层/选择逻辑和编辑表单拆分为 React 组件、hooks、类型和服务模块，避免主要业务 UI 继续依赖全局 `querySelector` 和动态 `innerHTML`。
|
||
4. 保留现有服务端 API 契约和 OSM 导入工作流；必要时只调整静态资源托管和开发/生产构建入口。
|
||
5. 保留 OpenLayers 地图的现有图层、样式、选择和交互行为，并确保状态变化正确驱动地图与检查器更新。
|
||
6. 提供开发模式和生产构建命令；Node 工作台服务能提供构建后的前端资源。
|
||
7. 为核心 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 重构。若本任务同时重做布局，交付周期和回归范围会显著增加。
|