OrgTJWater/next-tjwater-drainage-frontend
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: migrate drainage frontend to Vite

Browse Source
This commit is contained in:
jiang
2026-07-22 12:47:36 +08:00
parent e0cfa3d6eb
commit 72850761ce
213 changed files with 5726 additions and 5283 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+70 -110
View File
@@ -1,130 +1,90 @@
# Repository Guidelines
## Project Structure & Module Organization
## Project Structure
This repository is a Next.js App Router business system for an Agent-driven drainage-network WebGIS.
This repository is a Vite React single-page business system for an Agent-driven
drainage-network WebGIS. Runtime TypeScript lives under `src/`.
- `app/`: route entrypoints only. Keep `page.tsx`, `layout.tsx`, route-level loading/error, and metadata thin.
- `lib/`: shared utilities that are not owned by a feature.
- `features/map/core/`: reusable map UI and generic map helpers only. This layer should not know drainage-network business layer IDs, simulation scenarios, or Agent workflows.
- `features/workbench/`: the drainage-network WebGIS workbench. Put drainage-network sources, layers, simulation overlays, feature adapters, and workbench-specific map interactions here.
- `features/agent/`: Agent-facing task data, panels, and action recommendations. Agent code should produce typed action data instead of mutating the map or UI directly.
- `shared/` (planned): reusable UI, API clients, and cross-feature types once code is reused by multiple features.
- Root markdown files are product/design references and should not be treated as runtime code.
- `src/app/`: application shell and providers.
- `src/features/map/core/`: reusable map UI and generic map helpers. This layer
must not know drainage-network business layer IDs or Agent workflows.
- `src/features/workbench/`: drainage sources, layers, SCADA overlays, feature
adapters, scenarios, and workbench-specific interactions.
- `src/features/agent/`: Agent protocol, sessions, typed actions, panels, and
recommendations.
- `src/shared/`: reusable UI, AI elements, runtime configuration, and utilities.
- `src/mocks/`: MSW handlers and fixtures.
- `tests/browser/`: product-specific Playwright regressions.
- `public/`: static drainage and SCADA assets plus the runtime-config placeholder.
## Build, Test, and Development Commands
Do not add Next.js APIs or route handlers. Backend and BFF behavior belongs in
the Agent service or another service. Browser-safe GeoServer reads may happen
directly when CORS is enabled.
## Commands
Use `pnpm`.
```bash
pnpm dev
```
Starts the local development server at `http://localhost:3000`.
```bash
pnpm build
pnpm typecheck
pnpm lint
pnpm test
pnpm test:browser
```
Creates a production Next.js build. Stop `pnpm dev` before running this to avoid concurrent `.next` writes.
The Vite development server listens on `http://127.0.0.1:5173` by default.
`pnpm build` runs TypeScript validation before producing `dist/`.
## Coding Style
- Use TypeScript and React function components with explicit exported types at
module boundaries.
- Use two-space indentation and kebab-case filenames.
- Use PascalCase for components and types, camelCase for functions and values,
and `useXxx` for hooks.
- Keep orchestration components thin. Move sources, layers, event handling, and
feature adapters into focused modules.
- Keep MapLibre sources, layers, camera helpers, and interactions outside
presentational components.
- Keep Agent rendering schema-driven. Validate Agent output before it reaches
React, and represent map actions as typed data that can be previewed,
confirmed, applied, and rolled back.
## Domain Boundaries
- `src/features/map/core` owns generic controls, legends, camera helpers, and
reusable selection primitives.
- `src/features/workbench` owns conduits, junctions, orifices, outfalls, pumps,
SCADA sources, simulation overlays, and drainage-specific behavior.
- `src/features/agent` owns task reasoning UI and controlled recommendations.
Do not reintroduce supply-network layer IDs or assets into the drainage config.
GeoServer layer names, workspace defaults, map style tokens, titles, and Agent
copy must remain drainage-specific.
## Verification
Frontend changes should pass:
```bash
pnpm exec tsc --noEmit
```
Runs TypeScript validation without emitting files.
## Coding Style & Naming Conventions
- Use TypeScript and React function components. Prefer explicit props types over inline anonymous object types for reusable components.
- Use two-space indentation. Keep imports ordered: external packages first, then `@/` aliases, then local relative imports.
- Use kebab-case for filenames and folders: `feature-insight-panel.tsx`, `use-map-selection.ts`, `drainage-network-layers.ts`.
- Use PascalCase for React components and component types: `FeatureInsightPanel`, `MapWorkbenchPage`.
- Use camelCase for variables, functions, object fields, and non-component exports: `selectedFeatureId`, `createWaterNetworkSources`.
- Use `useXxx` for hooks: `useWorkbenchMap`, `usePanelLayout`.
- Use PascalCase type names with clear suffixes: `MapViewState`, `AgentUiResult`, `LayerConfig`, `FeatureInsightProps`.
- Use UPPER_SNAKE_CASE only for stable global constants: `WATER_NETWORK_BOUNDS`, `SOURCE_LAYERS`.
- Use named exports for feature modules. Avoid default exports except for Next.js route files under `app/`.
- Keep MapLibre sources, layers, camera helpers, and interactions outside presentational React components.
- Prefer typed configuration objects for GeoServer layers, Mapbox basemap settings, and Agent actions.
## Code Organization Style
Use thin orchestration components. A page component may compose panels, hooks, and map modules, but should not contain large mock datasets, layer specs, event handlers, and UI markup in one file.
Recommended future pattern:
```txt
features/map/core/
components/
base-layers-control.tsx
scale-line.tsx
toolbar.tsx
zoom.tsx
legend.tsx
layer-control.tsx
hooks/
use-map-camera.ts
use-layer-visibility.ts
use-map-selection.ts
map/
style.ts
layer-utils.ts
features/workbench/
map-workbench-page.tsx
components/
workbench-top-bar.tsx
simulation-dock.tsx
simulation-result-panel.tsx
hooks/use-workbench-map.ts
map/sources.ts
map/layers.ts
map/annotation-layers.ts
state/types.ts
features/agent/
components/agent-assistant-panel.tsx
data/agent-task.ts
types.ts
```
Agent actions should be data, not imperative UI mutations. Let the UI/map state layer validate, preview, confirm, apply, and roll back actions.
Keep the growth boundary clear:
- `features/map/core` owns generic map capabilities such as base layer controls, toolbars, legends, layer controls, camera helpers, and reusable selection primitives.
- `features/workbench` owns drainage-network domain behavior such as pipe, manhole, outfall, and pump-station sources, simulation overlays, feature detail adapters, scenario controls, and business-specific interactions.
- `features/agent` owns task reasoning UI and typed recommendations. It should communicate with the workbench through action objects such as `preview-impact`, `locate-feature`, or `set-layer-visible`.
## Testing Guidelines
There is no formal test suite yet. For now, required checks are:
```bash
pnpm exec tsc --noEmit
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```
When tests are added, colocate feature tests near the feature module or place shared integration tests under `tests/`. Name tests after behavior, for example `map-selection.test.ts`.
Run focused Playwright tests when changing visible behavior, responsive layout,
runtime configuration, or map interactions. Name tests after behavior.
## Commit & Pull Request Guidelines
## Configuration and Security
This directory currently has no Git history, so no existing commit convention can be inferred. Use concise, imperative commit messages such as:
Browser configuration is injected through `/runtime-config.js` and validated in
`src/shared/config/env.ts`. Use `DRAINAGE_*` variables. Legacy
`NEXT_PUBLIC_*` values are accepted by the Vite development adapter only to ease
local migration.
```txt
Add direct GeoServer MVT sources
Refactor map workbench shell
```
Pull requests should include:
- Summary of user-visible changes.
- Notes on map/data source changes.
- Screenshots for UI changes.
- Verification commands run.
## Security & Configuration Tips
Store local secrets in `.env.local`. Do not commit real tokens. The Mapbox token is read from:
```env
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
```
GeoServer MVT layers are loaded directly from `geoserver.waternetwork.cn`; confirm CORS remains enabled before removing fallbacks or changing hosts.
Do not commit secrets, `.env.local`, generated `dist/`, dependency folders,
Playwright artifacts, tokens, or session dumps. Keep server-only proxy targets
in untracked environment files.