生成agent instructions
This commit is contained in:
JIANG
+47
-161
@@ -1,174 +1,60 @@
|
||||
# Copilot Instructions for TJWater Frontend
|
||||
# Copilot Instructions for TJWaterFrontend_Refine
|
||||
|
||||
## Project Overview
|
||||
## Environment Setup
|
||||
|
||||
A Next.js 16 + TypeScript water network management system built with Refine framework, featuring real-time hydraulic simulation, SCADA data management, and GIS visualization using OpenLayers and Deck.gl.
|
||||
1. **Node.js**: Ensure you have Node.js v18 or later installed.
|
||||
2. **Dependencies**: Run `npm install` to install all project dependencies.
|
||||
3. **Environment Variables**: Create a `.env.local` file in the root directory with
|
||||
|
||||
## Build, Test, and Lint Commands
|
||||
Using bash setup dependencies:
|
||||
|
||||
```bash
|
||||
# Development
|
||||
npm run dev # Start dev server (uses 4GB memory allocation)
|
||||
|
||||
# Production
|
||||
npm run build # Build for production (standalone output)
|
||||
npm run start # Start production server
|
||||
|
||||
# Testing
|
||||
npm run test # Run all tests
|
||||
npm run test:watch # Run tests in watch mode
|
||||
npm run test:coverage # Generate coverage report
|
||||
|
||||
# Linting
|
||||
npm run lint # Run ESLint
|
||||
npm install
|
||||
```
|
||||
|
||||
**Run single test file:**
|
||||
## Build, Test, and Lint
|
||||
|
||||
```bash
|
||||
npm test -- path/to/test-file.test.ts
|
||||
```
|
||||
- **Dev Server**: `npm run dev` (Runs with increased memory limit: `--max_old_space_size=4096`)
|
||||
- **Build**: `npm run build`
|
||||
- **Lint**: `npm run lint` (ESLint)
|
||||
- **Test**: `npm run test` (Jest)
|
||||
- Run a specific test file: `npm run test -- <path/to/file>`
|
||||
- Run a specific test case: `npm run test -- -t 'test name'`
|
||||
|
||||
## Architecture
|
||||
## High-Level Architecture
|
||||
|
||||
### Framework Stack
|
||||
|
||||
- **Next.js 16** with App Router (not Pages Router)
|
||||
- **Refine** framework for admin/CRUD operations
|
||||
- **NextAuth.js** with Keycloak for SSO authentication
|
||||
- **Material-UI (MUI) v6** for UI components
|
||||
- **OpenLayers** + **Deck.gl** for map visualization
|
||||
|
||||
### Route Structure
|
||||
|
||||
- `src/app/layout.tsx` - Root layout with RefineContext
|
||||
- `src/app/(main)/` - Protected routes with shared layout
|
||||
- `/network-simulation` - Real-time network simulation
|
||||
- `/scada-data-cleaning` - SCADA data management
|
||||
- `/monitoring-place-optimization` - Sensor placement optimization
|
||||
- `/health-risk-analysis` - Health risk assessment
|
||||
- `/risk-analysis-location` - Risk location analysis
|
||||
- `/network-partition-optimization` - Network partitioning
|
||||
- `src/app/OlMap/` - Standalone map route with custom controls
|
||||
- `src/app/login/` - Public authentication pages
|
||||
|
||||
### Key Directories
|
||||
|
||||
- `src/app/_refine_context.tsx` - Refine configuration with resources, auth provider, and data provider
|
||||
- `src/providers/data-provider/` - REST API data provider (currently mock, update API_URL for production)
|
||||
- `src/contexts/color-mode/` - Theme switching (light/dark mode persisted in cookies)
|
||||
- `src/components/` - Reusable UI components (header, loading, olmap, title)
|
||||
- `src/utils/` - Map utilities (layers.ts, mapQueryService.ts, color parsing)
|
||||
- `src/config/config.ts` - Environment-based configuration with fallback defaults
|
||||
|
||||
### Path Aliases (TypeScript)
|
||||
|
||||
```typescript
|
||||
@app/* -> src/app/*
|
||||
@assets/* -> src/assets/*
|
||||
@components/* -> src/components/*
|
||||
@config/* -> src/config/*
|
||||
@contexts/* -> src/contexts/*
|
||||
@interfaces/* -> src/interfaces/*
|
||||
@libs/* -> src/libs/*
|
||||
@providers/* -> src/providers/*
|
||||
@utils/* -> src/utils/*
|
||||
@/* -> src/*
|
||||
```
|
||||
|
||||
### Map Architecture
|
||||
|
||||
The map system uses a hybrid approach:
|
||||
|
||||
- **OpenLayers** as the base map engine (vector tiles from GeoServer)
|
||||
- **Deck.gl** overlays for advanced visualizations (trips, contours, text labels)
|
||||
- **DeckLayer** custom class bridges OL and Deck.gl (`@utils/layers`)
|
||||
- Map data sourced from GeoServer MVT tiles (configured in `@config/config.ts`)
|
||||
- Layers: junctions, pipes, valves, reservoirs, pumps, tanks, scada
|
||||
|
||||
### Client vs Server Components
|
||||
|
||||
- Most interactive components use `"use client"` directive (~35 files)
|
||||
- Map components are always client-side (OpenLayers requires browser APIs)
|
||||
- Layout and page files without interactivity can be server components
|
||||
- **Framework**: **Next.js 16 (App Router)** integrated with **Refine** (`@refinedev/core`).
|
||||
- **Routing**:
|
||||
- Routes are defined in `src/app`.
|
||||
- Refine resources (e.g., `/network-simulation`, `/hydraulic-simulation/*`) map directly to these routes.
|
||||
- Configuration is central in `src/app/_refine_context.tsx`.
|
||||
- **State Management**:
|
||||
- **Global App State**: **Zustand** (`src/store`).
|
||||
- **Server State**: Managed by Refine hooks (`useList`, `useOne`, etc.) via **React Query**.
|
||||
- **Authentication**:
|
||||
- **NextAuth.js** handling Keycloak integration.
|
||||
- Session token is synced to Zustand (`useAuthStore`) in `RefineContext`.
|
||||
- **Data Layer**:
|
||||
- Custom Data Provider: `src/providers/data-provider`.
|
||||
- API Utilities: `src/lib/api.ts`, `src/lib/apiFetch.ts`.
|
||||
- **UI & Styling**:
|
||||
- **Material UI (MUI)**: Primary component library (`@mui/material`, `@refinedev/mui`).
|
||||
- **Tailwind CSS v4**: Utility classes for layout and custom styling (`@tailwindcss/postcss`).
|
||||
- **Mapping**: OpenLayers (`ol`), deck.gl, Turf.js.
|
||||
- **Charts**: ECharts, MUI X Charts.
|
||||
|
||||
## Key Conventions
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
- Keycloak SSO via NextAuth.js (`src/app/api/auth/[...nextauth]/`)
|
||||
- Session managed with `SessionProvider` wrapper
|
||||
- Auth check redirects to `/login` if unauthenticated
|
||||
- Use `useSession()` hook for current user data
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- All frontend-accessible variables must have `NEXT_PUBLIC_` prefix
|
||||
- Backend URL: `NEXT_PUBLIC_BACKEND_URL` (defaults to http://192.168.1.42:8000)
|
||||
- GeoServer URL: `NEXT_PUBLIC_MAP_URL` (defaults to http://127.0.0.1:8080/geoserver)
|
||||
- Map layers: `NEXT_PUBLIC_MAP_AVAILABLE_LAYERS` (comma-separated)
|
||||
- Keycloak config in `.env.local` (not committed)
|
||||
|
||||
### Refine Resources
|
||||
|
||||
Resources defined in `_refine_context.tsx` use Chinese labels and route to pages in `(main)/`:
|
||||
|
||||
- Each resource has: name (Chinese), list (route path), meta (icon + label)
|
||||
- Icons from `react-icons` library
|
||||
- No CRUD operations defined (list-only pages)
|
||||
|
||||
### Map Styling
|
||||
|
||||
- Default styles in `config.MAP_DEFAULT_STYLE` (stroke, circle, colors)
|
||||
- Circle radius uses zoom-based interpolation (1px at z12, 8px at z24)
|
||||
- WebGL rendering for vector tiles
|
||||
- Style legends generated dynamically in map controls
|
||||
|
||||
### TypeScript Configuration
|
||||
|
||||
- Strict mode enabled
|
||||
- Path aliases match jest.config.js mappings
|
||||
- Target ES5 for broader compatibility
|
||||
- Incremental builds enabled
|
||||
|
||||
### Next.js Configuration
|
||||
|
||||
- **Standalone output** for Docker deployment
|
||||
- SVG files handled by `@svgr/webpack` (imported as React components)
|
||||
- No custom server or middleware
|
||||
|
||||
### Testing Setup
|
||||
|
||||
- Jest with React Testing Library
|
||||
- jsdom environment for component testing
|
||||
- Path aliases configured to match tsconfig.json
|
||||
- Setup file at `jest.setup.js`
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Adding a New Route
|
||||
|
||||
1. Create directory in `src/app/(main)/your-route/`
|
||||
2. Add `page.tsx` and optional `loading.tsx`
|
||||
3. Register resource in `src/app/_refine_context.tsx` resources array
|
||||
4. Import icon from `react-icons`
|
||||
|
||||
### Working with Maps
|
||||
|
||||
- Use `MapComponent` from `src/app/OlMap/MapComponent.tsx`
|
||||
- Access map context via `useMapData()` hook
|
||||
- Vector tile layers auto-load from GeoServer workspace
|
||||
- Custom overlays use Deck.gl layers (TextLayer, TripsLayer, ContourLayer)
|
||||
|
||||
### API Calls
|
||||
|
||||
- Update `dataProvider` in `src/providers/data-provider/index.ts` for real backend
|
||||
- Currently points to `https://api.fake-rest.refine.dev`
|
||||
- Use Refine hooks (`useList`, `useOne`, etc.) for data fetching
|
||||
|
||||
### Theme Management
|
||||
|
||||
- Theme stored in cookies (not localStorage)
|
||||
- Toggle via `ColorModeContext` from `@contexts/color-mode`
|
||||
- Supports light/dark modes only
|
||||
- Default mode read from cookie in root layout (server-side)
|
||||
- **Refine Integration**:
|
||||
- Use Refine hooks (`useTable`, `useForm`, `useNavigation`) for data-heavy components.
|
||||
- Resources are defined in the `<Refine>` component in `src/app/_refine_context.tsx`.
|
||||
- **Project Structure**:
|
||||
- `src/components/`: Grouped by feature (e.g., `olmap`, `project`) or common UI elements.
|
||||
- `src/lib/`: Utility functions and API helpers.
|
||||
- `src/providers/`: Refine providers (data, etc.).
|
||||
- **Imports**:
|
||||
- Use absolute imports with `@/` alias (e.g., `@/components`, `@/store`, `@/lib`).
|
||||
- _Note_: `@libs` alias in tsconfig points to non-existent `src/libs` folder; prefer `@/lib`.
|
||||
- **Styling**:
|
||||
- Prefer MUI components for standard UI elements.
|
||||
- Use Tailwind utility classes for layout and custom overrides.
|
||||
|
||||
Reference in New Issue
Block a user