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