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.

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.

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.

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.

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.

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.