# 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 中。