feat: migrate drainage frontend to Vite

2026-07-22 12:47:36 +08:00
parent e0cfa3d6eb
commit 72850761ce
213 changed files with 5726 additions and 5283 deletions
@@ -1,22 +1,91 @@
-# Drainage Network Frontend
+# Next TJWater Drainage Frontend

-排水管网 WebGIS 业务系统，基于 `next-webgis` 基础项目创建。
+排水管网 WebGIS Agent 工作台。界面以地图为主视图，集成排水管渠、检查井、排放口、泵、SCADA 监测、异常工况、Agent 对话和受控前端动作。

-## 开发
+项目已从 Next.js App Router 迁移到 Vite、React 19、TypeScript 和 Tailwind CSS 4。地图基于 MapLibre GL，流向效果使用 deck.gl，Agent 消息支持代码高亮、数学公式和 Mermaid 图表。
+
+## 主要功能
+
+- 排水管网 MVT 图层和 SCADA 监测点展示
+- 地图缩放、测量、绘制、图层控制、要素定位和视图导出
+- 异常工况列表、详情分析和调度任务跟踪
+- Agent 流式对话、推荐问题、会话管理和权限批准
+- 经过 Schema 校验的 UI Envelope 和前端动作执行
+- 运行时配置注入、MSW 本地模拟和开发面板
+
+## 开发环境

 ```bash
+corepack enable
 pnpm install
+cp .env.example .env.local
 pnpm dev
 ```

-默认访问地址为 <http://localhost:3000>。
+开发服务器默认地址为 <http://127.0.0.1:5173>。完整对话功能需要同时启动 Agent 后端。

-## 校验
+## 运行时配置
+
+浏览器配置通过 `/runtime-config.js` 注入，不使用 `VITE_` 前缀。开发环境可在 `.env.local` 中设置：
+
+| 变量                           | 默认值                                        | 说明                                   |
+| ------------------------------ | --------------------------------------------- | -------------------------------------- |
+| `DRAINAGE_MAPBOX_ACCESS_TOKEN` | 空                                            | Mapbox 底图访问令牌                    |
+| `DRAINAGE_MAP_URL`             | `https://geoserver.waternetwork.cn/geoserver` | GeoServer 服务地址                     |
+| `DRAINAGE_GEOSERVER_WORKSPACE` | `wenzhou`                                     | 排水数据工作区                         |
+| `DRAINAGE_AGENT_API_BASE_URL`  | `http://127.0.0.1:8787`                       | 浏览器访问的 Agent 服务地址            |
+| `DRAINAGE_TTS_API_URL`         | `/api/tts/edge`                               | 语音合成接口地址                       |
+| `DRAINAGE_ENABLE_DEV_PANEL`    | `false`                                       | 是否显示开发面板                       |
+| `DRAINAGE_ENABLE_MSW`          | `false`                                       | 是否启用浏览器端 Mock Service Worker   |
+| `AGENT_API_INTERNAL_BASE_URL`  | `http://127.0.0.1:8787`                       | Vite 开发代理访问的 Agent 服务地址     |
+| `TTS_API_INTERNAL_BASE_URL`    | `http://127.0.0.1:8790`                       | Vite/Caddy 代理访问的独立 TTS 服务地址 |
+
+Vite 开发适配器会兼容现有 `.env.local` 中的 `NEXT_PUBLIC_*` 变量，生产容器应使用 `DRAINAGE_*` 变量。
+
+排水要素定位在浏览器中直接请求 GeoServer WFS，因此部署环境需保留 GeoServer CORS。Agent 流式接口使用 `DRAINAGE_AGENT_API_BASE_URL`。语音合成依赖独立 TTS 服务；默认站内路径会由 Vite 或容器内 Caddy 转发到 `TTS_API_INTERNAL_BASE_URL`。
+
+## 常用命令

 ```bash
-pnpm lint
-pnpm exec tsc --noEmit
-pnpm build
+pnpm dev          # 启动 Vite 开发服务器
+pnpm build        # 类型检查并生成生产构建
+pnpm preview      # 预览生产构建
+pnpm typecheck    # 运行 TypeScript 检查
+pnpm lint         # 运行 ESLint
+pnpm format       # 使用 Prettier 格式化文件
+pnpm test         # 运行 Vitest 单元测试
+pnpm test:watch   # 监听模式运行单元测试
+pnpm test:browser # 运行 Playwright 浏览器测试
 ```

-地图服务和公开配置通过 `.env.local` 提供；可从 `.env.example` 创建本地配置，真实令牌不得提交。
+## Docker
+
+生产镜像使用 Node.js 构建静态文件，并通过 Caddy 提供服务。容器启动时根据环境变量生成 `/runtime-config.js`。
+
+```bash
+docker build -t next-tjwater-drainage-frontend .
+docker run --rm -p 8080:80 --env-file .env.local next-tjwater-drainage-frontend
+```
+
+启动后访问 <http://localhost:8080>。
+
+## 项目结构
+
+```text
+src/
+├── app/                 应用入口、Provider 和基础浏览器回归测试
+├── features/
+│   ├── agent/           Agent 协议、会话、动作执行和界面组件
+│   ├── map/             地图核心控件
+│   └── workbench/       排水业务、SCADA、调度面板和地图编排
+├── mocks/               MSW handlers 和测试数据
+├── shared/              通用 UI、AI 元素、配置和工具
+├── test/                Vitest 测试环境
+└── styles.css           Tailwind CSS 入口和全局样式
+```
+
+产品级浏览器回归仍位于 `tests/browser/`。
+
+## 构建说明
+
+生产构建可能提示 deck.gl 和 luma.gl 的第三方循环分块，以及 Shiki、Mermaid 语言包超过 Rollup 默认阈值。只要构建成功，这些提示不影响静态产物生成。