From 4596af7c1259484696d156eacdcf13968e0a88d4 Mon Sep 17 00:00:00 2001
From: Huarch <huarch97@outlook.com>
Date: Wed, 22 Jul 2026 11:26:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BC=96=E5=86=99=E4=B8=AD=E6=96=87=20?=
 =?UTF-8?q?README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.MD | 101 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 72 insertions(+), 29 deletions(-)

diff --git a/README.MD b/README.MD
index c36023c..f938430 100644
--- a/README.MD
+++ b/README.MD
@@ -1,48 +1,91 @@
-# my-refine-app
+# TJWaterFrontend_Refine 内部前端
 
-<div align="center" style="margin: 30px;">
-    <a href="https://refine.dev">
-    <img alt="refine logo" src="https://refine.ams3.cdn.digitaloceanspaces.com/readme/refine-readme-banner.png">
-    </a>
-</div>
-<br/>
+`TJWaterFrontend_Refine` 是 TJWater 内部 Web 前端，基于 Refine、Next.js、React 和 MUI 构建。它承载管网地图、业务管理、用户认证、智能体聊天、SCADA/历史数据查看和结果可视化等内部功能。
 
-This [Refine](https://github.com/refinedev/refine) project was generated with [create refine-app](https://github.com/refinedev/refine/tree/master/packages/create-refine-app).
+## 技术栈
 
-## Getting Started
+- Next.js 16
+- React 19
+- Refine 5
+- MUI 6 / MUI X
+- OpenLayers、deck.gl、Turf
+- Zustand、NextAuth、Jest
 
-A React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility ✨
+## 目录结构
 
-Refine's hooks and components simplifies the development process and eliminates the repetitive tasks by providing industry-standard solutions for crucial aspects of a project, including authentication, access control, routing, networking, state management, and i18n.
-
-## Available Scripts
-
-### Running the development server.
-
-```bash
-    npm run dev
+```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    本地编排参考
 ```
 
-### Building for production.
+新增功能应复用现有页面、组件、provider、地图和聊天结构，避免创建平行体系。
+
+## 本地开发
+
+要求 Node.js 20 或更高版本：
 
 ```bash
-    npm run build
+npm install
+npm run dev
 ```
 
-### Running the production server.
+`npm run dev` 会先执行运行时配置生成，再启动 Next.js 开发服务。
+
+## 常用命令
 
 ```bash
-    npm run start
+npm run lint
+npm test
+npm run test:coverage
+npm run build
+npm run start
+docker build -t tjwater-frontend:local .
 ```
 
-## Learn More
+- `npm run lint`：运行 ESLint。
+- `npm test`：运行 Jest。
+- `npm run test:coverage`：生成测试覆盖率。
+- `npm run build`：生成生产构建。
+- `npm run start`：启动生产模式服务。
 
-To learn more about **Refine**, please check out the [Documentation](https://refine.dev/docs)
+## 配置说明
 
-- **REST Data Provider** [Docs](https://refine.dev/docs/core/providers/data-provider/#overview)
-- **Material UI** [Docs](https://refine.dev/docs/ui-frameworks/mui/tutorial/)
-- **Custom Auth Provider** [Docs](https://refine.dev/docs/core/providers/auth-provider/)
+运行时配置由 `scripts/generate-runtime-config.mjs` 生成。API 地址、Agent 地址、Keycloak/认证参数、地图服务地址和其他环境差异配置应通过环境变量或部署配置注入。
 
-## License
+只有允许暴露给浏览器的配置才应进入 public/runtime 配置；密钥和私有 token 不能进入前端构建产物。
 
-MIT
+## 开发规范
+
+- 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 中。