2026-02-12 10:31:53 +08:00
|
|
|
# Repository Guidelines
|
|
|
|
|
|
|
|
|
|
## Project Structure & Module Organization
|
2026-02-12 15:37:49 +08:00
|
|
|
- `app/` contains application logic (controllers, models, services).
|
|
|
|
|
- `resources/views/` stores Blade templates for public pages and admin UI.
|
|
|
|
|
- `routes/web.php` defines frontend/admin routes.
|
|
|
|
|
- `database/migrations/` contains schema and data migration files.
|
|
|
|
|
- `tests/Feature/` and `tests/Unit/` hold feature and unit tests.
|
|
|
|
|
- `public/` serves static assets; uploaded files are exposed via `public/storage`.
|
2026-02-12 10:31:53 +08:00
|
|
|
|
|
|
|
|
## Build, Test, and Development Commands
|
2026-02-12 15:37:49 +08:00
|
|
|
- `composer install` installs PHP dependencies.
|
|
|
|
|
- `npm install` installs frontend dependencies.
|
|
|
|
|
- `composer run dev` starts local Laravel + Vite development workflow.
|
|
|
|
|
- `php artisan migrate` runs database migrations.
|
|
|
|
|
- `composer test` clears config and runs test suite.
|
|
|
|
|
- `php artisan storage:link` creates the `/storage` public symlink for uploads.
|
2026-02-12 10:31:53 +08:00
|
|
|
|
|
|
|
|
## Coding Style & Naming Conventions
|
2026-02-12 15:37:49 +08:00
|
|
|
- Follow PSR-12 for PHP; use 4-space indentation.
|
|
|
|
|
- Use strict types (`declare(strict_types=1);`) in PHP files.
|
|
|
|
|
- Class names: `PascalCase`; methods/variables: `camelCase`; constants: `UPPER_SNAKE_CASE`.
|
|
|
|
|
- Blade components should be reusable and grouped by domain (e.g. `resources/views/components/portal/`).
|
|
|
|
|
- Keep controller actions focused; extract reusable logic to private methods/services.
|
2026-02-12 10:31:53 +08:00
|
|
|
|
|
|
|
|
## Testing Guidelines
|
2026-02-12 15:37:49 +08:00
|
|
|
- Write unit tests for pure logic in `tests/Unit/`.
|
|
|
|
|
- Write feature tests for routes/forms/permissions in `tests/Feature/`.
|
|
|
|
|
- Name tests by behavior, e.g. `test_admin_can_update_home_modules`.
|
|
|
|
|
- Run `composer test` before opening a PR.
|
2026-02-12 10:31:53 +08:00
|
|
|
|
|
|
|
|
## Commit & Pull Request Guidelines
|
2026-02-12 15:37:49 +08:00
|
|
|
- Use clear, scoped commit messages, e.g. `feat(admin): add structured home module settings`.
|
|
|
|
|
- Keep commits focused; avoid mixing unrelated refactors.
|
|
|
|
|
- PRs should include:
|
|
|
|
|
- What changed and why
|
|
|
|
|
- Screenshots/GIFs for UI updates
|
|
|
|
|
- Migration/rollback notes if schema changes
|
|
|
|
|
- Test coverage notes or manual verification steps
|
2026-02-12 10:31:53 +08:00
|
|
|
|
|
|
|
|
## Security & Configuration Tips
|
2026-02-12 15:37:49 +08:00
|
|
|
- Never commit `.env` or secrets.
|
|
|
|
|
- Ensure `APP_URL` is correct in each environment.
|
|
|
|
|
- For markdown/image uploads, prefer relative `/storage/...` paths to avoid host lock-in.
|
|
|
|
|
- Validate all admin inputs (URL type, route whitelist, required fields) before persistence.
|
|
|
|
|
|
