# Repository Guidelines

## Project Structure & Module Organization
- `app/` contains core backend code (`Http/Controllers`, `Services`, `Models`, `Support`, `Enums`).
- `routes/web.php` defines HTTP routes; `routes/console.php` holds CLI routes.
- `resources/views` stores Blade templates, while `resources/js` and `resources/css` are Vite frontend entry points.
- `database/migrations`, `database/seeders`, and `database/factories` manage schema and seed data.
- `tests/Feature` covers HTTP/integration behavior; `tests/Unit` covers isolated domain logic.
- `public/` is web root; generated assets are bundled by Vite.

## Build, Test, and Development Commands
- `composer install` — install PHP dependencies.
- `npm install` — install frontend build tooling.
- `composer setup` — one-shot project bootstrap (`.env`, key, migration, frontend build).
- `composer dev` — run local development stack (Laravel server, queue listener, logs, Vite).
- `php artisan serve` — run backend only.
- `npm run dev` / `npm run build` — start Vite dev server or build production assets.
- `composer test` (or `php artisan test`) — clear config and run test suites.

## Coding Style & Naming Conventions
- Follow `.editorconfig`: UTF-8, LF, 4-space indent (YAML: 2 spaces), trim trailing whitespace.
- PHP follows PSR-12 and Laravel conventions; format with `./vendor/bin/pint` before PR.
- Use PSR-4 namespaces under `App\` with clear suffixes (`*Controller`, `*Request`, `*Service`).
- Use `StudlyCase` for classes, `camelCase` for methods/variables, and `snake_case` for DB columns/migration names.

## Testing Guidelines
- Framework: PHPUnit 11 via Laravel test runner.
- Place tests in `tests/Feature` or `tests/Unit`; filename pattern: `*Test.php`.
- Add/adjust tests for every behavioral change; prioritize Feature tests for route/controller updates.
- Keep tests deterministic; use factories/seed data and avoid external service dependencies.

## Commit & Pull Request Guidelines
- Current history uses short summaries (e.g., `init`, `添加 1`); keep commits concise, imperative, and scoped.
- Prefer format like `feat: add admin article filter` or `fix: validate model score bounds`.
- PRs should include: purpose, key changes, test evidence (`composer test` output), and related issue IDs.
- Include screenshots/GIFs for UI changes under `resources/views` or frontend assets.

## Security & Configuration Tips
- Never commit secrets from `.env`; keep `.env.example` updated for new config keys.
- Use least-privilege credentials for local/dev databases.
- Validate and authorize all admin-side inputs using Form Requests and middleware.