diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f640859..a8cc01f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ ## Project Overview -A Next.js 15 + 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. +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. ## Build, Test, and Lint Commands @@ -24,6 +24,7 @@ npm run lint # Run ESLint ``` **Run single test file:** + ```bash npm test -- path/to/test-file.test.ts ``` @@ -31,13 +32,15 @@ npm test -- path/to/test-file.test.ts ## Architecture ### Framework Stack -- **Next.js 15** with App Router (not Pages Router) + +- **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 @@ -50,6 +53,7 @@ npm test -- path/to/test-file.test.ts - `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) @@ -58,6 +62,7 @@ npm test -- path/to/test-file.test.ts - `src/config/config.ts` - Environment-based configuration with fallback defaults ### Path Aliases (TypeScript) + ```typescript @app/* -> src/app/* @assets/* -> src/assets/* @@ -72,7 +77,9 @@ npm test -- path/to/test-file.test.ts ``` ### 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`) @@ -80,6 +87,7 @@ The map system uses a hybrid approach: - 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 @@ -87,12 +95,14 @@ The map system uses a hybrid approach: ## 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) @@ -100,29 +110,35 @@ The map system uses a hybrid approach: - 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 @@ -131,23 +147,27 @@ Resources defined in `_refine_context.tsx` use Chinese labels and route to pages ## 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