2.2 KiB
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:
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.