20 lines
3.1 KiB
Markdown
20 lines
3.1 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
The primary Vite application lives in `src/`, with feature folders such as `components/ai`, `components/auth`, and `components/dashboard` grouping screens, while shared primitives stay in `components/ui` alongside the `cn` helper. Domain utilities and integrations sit in `lib/`, typed contracts in `types/`, and global styles in `styles/`. Reference notes, migration guides, and UX briefs belong in `docs/`. Build artifacts are staged in `build/` and `bundles/` - regenerate them instead of editing in place. The `crop-x/` workspace hosts the API-driven Next.js toolchain, and `nextjs-frontend/` contains a Jest-enabled prototype; treat each as an isolated package with its own dependencies.
|
||
|
||
## Build, Test, and Development Commands
|
||
Install dependencies with `npm install` at the repository root before any work. Launch the Vite dev server via `npm run dev` and build production bundles with `npm run build`. When touching the Next.js workspace, switch into `crop-x/` (or `nextjs-frontend/`) and run the same `npm run dev` / `npm run build` loop; lint with `npm run lint` and regenerate OpenAPI clients through `npm run generate-client`. The Next.js prototype keeps Jest wired - execute `npm test` or `npm run coverage` from `nextjs-frontend/` to validate UI contracts.
|
||
|
||
## Coding Style & Naming Conventions
|
||
Author components as TypeScript function components, export them with PascalCase names, and keep props camelCase. Align layout and spacing with Tailwind classes; reach for `components/ui` primitives before adding bespoke markup. Follow the established single-quote, semicolon-terminated formatting visible in `src/App.tsx`. In the Next.js packages, run Prettier (`npm run prettier`) when formatting cross-file changes and keep ESLint green before opening a review.
|
||
|
||
## Testing Guidelines
|
||
Automated coverage is concentrated in `nextjs-frontend/__tests__` using Jest and Testing Library; mirror existing file naming (`*.test.tsx`) when adding scenarios. For the Vite app, smoke the key dashboards after significant UI changes: authentication, machinery, fields, operations, assets, AI models, and irrigation. Document manual steps or screenshots in the PR when you touch flows without automated tests.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
Commit messages currently follow the "<22><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ϵͳ - <summary>" prefix; keep that Chinese tag and supply a short, imperative summary. Group related changes per commit so reviewers can bisect easily. Pull requests should describe the user-visible impact, list any config or schema updates, and attach before/after captures for UI adjustments. Link tracking tickets where possible and flag required environment variables (`VITE_API_BASE_URL`, etc.) if they change.
|
||
|
||
## Security & Configuration Tips
|
||
Never commit secrets - use `.env.local` entries for API hosts and credentials, and document new keys in `docs/` instead. When adding third-party scripts, load them through vetted helpers like `lib/mapLoader` to keep CSP compliance intact. Review generated OpenAPI clients before shipping to ensure endpoints line up with the deployed backend.
|