From 216c7b1ab9a120f8835e54fca38b685cad58a899 Mon Sep 17 00:00:00 2001
From: Huarch <huarch97@outlook.com>
Date: Tue, 9 Jun 2026 18:18:22 +0800
Subject: [PATCH] docs: add repository guidelines

---
 AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a0cfc22
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is the TJWater web frontend built with Refine, Next.js, React, and MUI. Application source lives under the existing Next.js project folders. Reuse established page, component, provider, map, and chat patterns instead of adding parallel structures. Static assets and public files should remain in the existing asset/public locations. Build output (`.next/`), dependency folders, and local caches are generated and must not be edited by hand.
+
+Deployment files are `Dockerfile`, `docker-compose.yml`, and `.gitea/workflows/package.yml`.
+
+## Build, Test, and Development Commands
+
+Use npm and Node 20 or newer:
+
+```bash
+npm install
+npm run dev
+npm run lint
+npm test
+npm run test:coverage
+npm run build
+npm run start
+```
+
+`npm run dev` starts the Refine/Next development server. `npm run lint` runs ESLint. `npm test` runs Jest. `npm run build` creates the production build.
+
+## Coding Style & Naming Conventions
+
+Use TypeScript and React function components. Follow ESLint and Next.js conventions. Use `PascalCase` for components, `camelCase` for variables/functions, and descriptive feature-oriented filenames. Prefer MUI components and existing design tokens/patterns for UI. Keep operational screens dense, clear, and task-focused.
+
+## Testing Guidelines
+
+Tests use Jest with React Testing Library. Name tests `*.test.ts` or `*.test.tsx` near the related code when possible. Add tests for user-visible behavior, state transitions, route guards, data transforms, and map/chat interactions. Run `npm test` or `npm run test:coverage` before larger PRs.
+
+## Commit & Pull Request Guidelines
+
+History uses Conventional Commit messages such as `feat(map): add coordinate zoom action` and `fix(chat): hide raw permission metadata`, with occasional Chinese summaries. Prefer `feat(scope):`, `fix(scope):`, or `refactor(scope):`.
+
+PRs should include a UI/behavior summary, verification commands, screenshots for visual changes, and notes for changed environment variables or backend API expectations.
+
+## Security & Configuration Tips
+
+Do not commit `.env`, `.next/`, `node_modules/`, local caches, or private map/API tokens. Public build-time variables should be documented; sensitive values belong in Gitea secrets.