jiang
4a522bf42a
Persist versioned models and validated network metadata in IndexedDB. Show scene download progress and recoverable errors with the existing frosted material. Connect existing skeletons to pending navigation and route boundaries while preserving the map. Previously only dynamic imports showed fallbacks, and rejected model promises prevented retries. Verified: 32 focused unit tests; 4 navigation and scene browser checks; 7 cache browser checks including invalid-metadata recovery; isolated production build and type checks.
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 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。
测试与发布
提交前建议运行：
npm run lint
npm test
发布镜像前运行：
npm run build
Gitea 包工作流位于 .gitea/workflows/package.yml，通常由 tag 触发构建和推送镜像。
Playwright E2E
首次运行先安装 Chromium：
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 登录状态：
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 中。