131 lines
5.3 KiB
Markdown
131 lines
5.3 KiB
Markdown
# 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.
|