diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a8cc01f..0fea55e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -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 -- ` + - 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 `` 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.