feat: initialize drainage network frontend

AGENTS.md

@@ -0,0 +1,130 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is a Next.js App Router business system for an Agent-driven drainage-network WebGIS.
+
+- `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.
+
+## Build, Test, and Development Commands
+
+Use `pnpm`.
+
+```bash
+pnpm dev
+```
+Starts the local development server at `http://localhost:3000`.
+
+```bash
+pnpm build
+```
+Creates a production Next.js build. Stop `pnpm dev` before running this to avoid concurrent `.next` writes.
+
+```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 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`.
+
+## Commit & Pull Request Guidelines
+
+This directory currently has no Git history, so no existing commit convention can be inferred. Use concise, imperative commit messages such as:
+
+```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.