124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
# TJWaterFrontend_Refine 内部前端
|
||
|
||
`TJWaterFrontend_Refine` 是 TJWater 内部 Web 前端，基于 Refine、Next.js、React 和 MUI 构建。它承载管网地图、业务管理、用户认证、智能体聊天、SCADA/历史数据查看和结果可视化等内部功能。
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 16
|
||
- React 19
|
||
- Refine 5
|
||
- MUI 6 / MUI X
|
||
- OpenLayers、deck.gl、Turf
|
||
- Zustand、NextAuth、Jest
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
src/app/ Next.js App Router 页面
|
||
src/components/ 复用 UI 组件
|
||
src/providers/ Refine、认证、数据和主题 provider
|
||
src/hooks/ 业务 hooks
|
||
src/utils/ 通用工具
|
||
public/ 静态资源
|
||
scripts/ 运行时配置和辅助脚本
|
||
Dockerfile 镜像构建文件
|
||
docker-compose.yml 本地编排参考
|
||
```
|
||
|
||
新增功能应复用现有页面、组件、provider、地图和聊天结构，避免创建平行体系。
|
||
|
||
## 本地开发
|
||
|
||
要求 Node.js 20 或更高版本：
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
`npm run dev` 会先执行运行时配置生成，再启动 Next.js 开发服务。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
npm run lint
|
||
npm test
|
||
npm run test:coverage
|
||
npm run test:e2e
|
||
npm run build
|
||
npm run start
|
||
docker build -t tjwater-frontend:local .
|
||
```
|
||
|
||
- `npm run lint`：运行 ESLint。
|
||
- `npm test`：运行 Jest。
|
||
- `npm run test:coverage`：生成测试覆盖率。
|
||
- `npm run test:e2e`：启动本地 Next.js 与 Playwright Chromium 烟测。
|
||
- `npm run build`：生成生产构建。
|
||
- `npm run start`：启动生产模式服务。
|
||
|
||
## 配置说明
|
||
|
||
运行时配置由 `scripts/generate-runtime-config.mjs` 生成。API 地址、Agent 地址、Keycloak/认证参数、地图服务地址和其他环境差异配置应通过环境变量或部署配置注入。
|
||
|
||
只有允许暴露给浏览器的配置才应进入 public/runtime 配置；密钥和私有 token 不能进入前端构建产物。
|
||
|
||
## 开发规范
|
||
|
||
- React 组件文件使用 `PascalCase.tsx`。
|
||
- 普通 TypeScript 模块、hooks、store、provider 和工具使用 `camelCase.ts`。
|
||
- `src/app` 路由目录使用 `kebab-case`，保留 Next.js 路由组和动态段语法。
|
||
- UI 优先沿用 MUI、Refine 和既有地图/聊天界面模式。
|
||
- 与后端或 Agent 通信的字段保持接口原始格式，通常为 `snake_case`。
|
||
|
||
## 测试与发布
|
||
|
||
提交前建议运行：
|
||
|
||
```bash
|
||
npm run lint
|
||
npm test
|
||
```
|
||
|
||
发布镜像前运行：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
Gitea 包工作流位于 `.gitea/workflows/package.yml`，通常由 tag 触发构建和推送镜像。
|
||
|
||
### Playwright E2E
|
||
|
||
首次运行先安装 Chromium：
|
||
|
||
```bash
|
||
npm run e2e:install
|
||
npm run test:e2e
|
||
```
|
||
|
||
本地测试会自动构建生产版本并启动隔离的 `http://127.0.0.1:3100`，生成仅用于测试的 NextAuth
|
||
会话，并模拟后端 API，因此不要求启动 Keycloak、Server 或 Agent。失败时可通过
|
||
`npm run test:e2e:report` 查看 HTML 报告，交互调试可使用
|
||
`npm run test:e2e:ui` 或 `npm run test:e2e:debug`。
|
||
|
||
在不能访问 Playwright CDN 的内网环境，可设置
|
||
`E2E_CHROMIUM_PATH=/absolute/path/to/chrome` 复用预装的 Chromium/Chrome。
|
||
|
||
若要对已部署环境运行测试，请传入环境地址和预先保存的管理员 Playwright 登录状态：
|
||
|
||
```bash
|
||
E2E_BASE_URL=https://example.test \
|
||
E2E_STORAGE_STATE=/absolute/path/to/storage-state.json \
|
||
E2E_USE_REAL_SERVICES=true \
|
||
npm run test:e2e
|
||
```
|
||
|
||
`E2E_BASE_URL` 会关闭本地开发服务器；`E2E_STORAGE_STATE` 避免在仓库中保存账号或
|
||
会话；`E2E_USE_REAL_SERVICES=true` 会关闭 API 模拟。Gitea 的
|
||
`.gitea/workflows/e2e.yml` 在分支推送和 PR 中运行同一组 Chromium 测试。
|
||
|
||
## 安全规则
|
||
|
||
不要提交 `.env`、`.next/`、`node_modules/`、本地缓存、私有地图/API token、客户数据或部署密钥。CI/CD 凭据应放在 Gitea secrets 中。
|