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

目录结构

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 或更高版本：

npm install
npm run dev

npm run dev 会先执行运行时配置生成，再启动 Next.js 开发服务。

常用命令

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。

测试与发布

提交前建议运行：

npm run lint
npm test

发布镜像前运行：

npm run build

Gitea 包工作流位于 .gitea/workflows/package.yml，通常由 tag 触发构建和推送镜像。

安全规则

不要提交 .env、.next/、node_modules/、本地缓存、私有地图/API token、客户数据或部署密钥。CI/CD 凭据应放在 Gitea secrets 中。