xiaomai
227c64d346
Introduce structural CSS classes for page shells, headers, and surface cards Update primary theme color to red and neutral to zinc across the application
46 lines
3.1 KiB
Markdown
46 lines
3.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This is a Nuxt 4 dinner ticket system using Vue, Nitro, PostgreSQL, Redis, Tailwind CSS, and Nuxt UI. Frontend code lives under `app/`: pages, components, layouts, composables, middleware, and global styles. Server code lives under `server/`: API handlers in `server/api`, startup plugins in `server/plugins`, and database/auth/session helpers in `server/utils`. Shared TypeScript helpers live in `shared/`; static assets in `public/`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
- `pnpm install`: install dependencies using the pinned pnpm version.
|
|
- `pnpm dev`: start the Nuxt development server.
|
|
- `pnpm build`: build the production Nitro app.
|
|
- `pnpm preview` or `pnpm start`: preview or run the built app.
|
|
- `docker compose up --build`: start the app with PostgreSQL and Redis.
|
|
- `docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build`: run the Docker hot-reload stack.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use TypeScript, Vue single-file components, and existing Nuxt conventions. Match the current style: 2-space indentation, single quotes, no semicolons, and explicit helpers. Name Nitro handlers by route and method, such as `server/api/bookings.get.ts` or `server/api/public/bookings/[token]/confirm.post.ts`. Keep server-only logic in `server/utils`, browser-facing logic in `app/composables`, and shared validation or formatting in `shared/`. Prefer Nuxt UI and Tailwind utilities over custom CSS unless styling is global.
|
|
|
|
## Testing Guidelines
|
|
|
|
No dedicated unit test framework is configured yet. `pnpm build` is the current verification gate, but agents should not run tests or builds in WSL unless explicitly asked; the maintainer will run them and report failures. For PostgreSQL, Redis, sessions, WebAuthn, or WhatsApp changes, verify with Docker and `GET /api/health`. If tests are added later, place them near the covered feature and document the command.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
The Git history follows Conventional Commit-style messages, commonly `feat(scope): summary`, `fix(scope): summary`, `refactor(scope): summary`, and `build: summary`. Use scopes like `bookings`, `auth`, `users`, `i18n`, or `receipt`. Pull requests should include a concise description, verification steps, linked issues when applicable, and screenshots for UI changes. Note required `.env` changes, migrations, or Docker impacts.
|
|
|
|
## Security & Configuration Tips
|
|
|
|
Create local configuration from `.env.example`. Do not commit secrets, session keys, database URLs with credentials, or WhatsApp tokens. Keep `NUXT_PUBLIC_APP_URL` aligned with the browser origin because WebAuthn requires a stable relying-party origin.
|
|
|
|
## UI Safety Rules (CRITICAL)
|
|
|
|
User-facing UI must NEVER contain:
|
|
|
|
- prompts
|
|
- remarks
|
|
- planning notes
|
|
- debug messages
|
|
- explanations of what was changed
|
|
- internal field names like `debug`, `meta`, `internal`
|
|
|
|
## Agent-Specific Instructions
|
|
|
|
Keep implementations concise and scoped to the requested behavior. Prefer the smallest code change that fits existing patterns, and avoid unrelated refactors, formatting churn, or broad rewrites.
|