92 lines
2.6 KiB
Markdown
92 lines
2.6 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 build
|
|
npm run start
|
|
docker build -t tjwater-frontend:local .
|
|
```
|
|
|
|
- `npm run lint`：运行 ESLint。
|
|
- `npm test`：运行 Jest。
|
|
- `npm run test:coverage`：生成测试覆盖率。
|
|
- `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 触发构建和推送镜像。
|
|
|
|
## 安全规则
|
|
|
|
不要提交 `.env`、`.next/`、`node_modules/`、本地缓存、私有地图/API token、客户数据或部署密钥。CI/CD 凭据应放在 Gitea secrets 中。
|