109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
# Project Conventions
|
|
|
|
## Test database safety
|
|
|
|
- Tests must use SQLite `:memory:` through `tests/bootstrap.php` and `Tests\TestCase`.
|
|
- Never run tests, `migrate:fresh`, `migrate:refresh`, or `db:wipe` against a persistent database, including the developer's `shopit` database.
|
|
- Never bypass the connection safety guard to resolve test failures. Use `php tests/verify-database-safety.php` to verify isolation without queries or migrations.
|
|
|
|
## Architecture
|
|
|
|
This project uses a domain-oriented structure grouped by business area under
|
|
`app/Domains`. Cross-cutting modules live under `app/Shared`.
|
|
|
|
Business domains must live in:
|
|
|
|
```text
|
|
app/Domains/<Area>/<DomainName>/
|
|
```
|
|
|
|
The current areas are `Core`, `Commerce`, and `Ticketing`. Cross-cutting
|
|
modules live in `app/Shared/<ModuleName>/`.
|
|
|
|
Supported folders inside each domain:
|
|
|
|
```text
|
|
app/Domains/<Area>/<DomainName>/
|
|
├── Models/
|
|
├── Controllers/
|
|
├── Requests/
|
|
├── Resources/
|
|
├── Services/
|
|
├── Policies/
|
|
├── Exceptions/
|
|
└── routes/
|
|
```
|
|
|
|
## Routing
|
|
|
|
- Root API routes live in `routes/api.php`.
|
|
- `routes/api.php` should act as an aggregator only.
|
|
- Each business domain defines its own routes in
|
|
`app/Domains/<Area>/<DomainName>/routes/api.php`.
|
|
- Shared modules that expose routes define them in
|
|
`app/Shared/<ModuleName>/routes/api.php`.
|
|
|
|
## Namespaces
|
|
|
|
Use this namespace pattern:
|
|
|
|
```php
|
|
App\Domains\<Area>\<DomainName>\Models
|
|
App\Domains\<Area>\<DomainName>\Controllers
|
|
App\Domains\<Area>\<DomainName>\Requests
|
|
App\Domains\<Area>\<DomainName>\Resources
|
|
App\Domains\<Area>\<DomainName>\Services
|
|
App\Domains\<Area>\<DomainName>\Policies
|
|
App\Domains\<Area>\<DomainName>\Exceptions
|
|
```
|
|
|
|
For cross-cutting modules, use `App\Shared\<ModuleName>\...`. Reusable enums
|
|
and rules live directly under `App\Shared`.
|
|
|
|
## Responsibilities
|
|
|
|
- `Models/`: Eloquent models and model relationships.
|
|
- `Controllers/`: HTTP entrypoints only.
|
|
- `Requests/`: validation and request authorization with `FormRequest`.
|
|
- `Resources/`: API response transformation with `JsonResource`.
|
|
- `Services/`: business logic and application workflows.
|
|
- `Policies/`: authorization rules.
|
|
- `Exceptions/`: domain-specific exceptions.
|
|
- `routes/`: domain route definitions.
|
|
|
|
## Controller Rules
|
|
|
|
- Controllers should stay thin.
|
|
- Do not validate inline in controllers when a `FormRequest` can be used.
|
|
- Do not place business logic in controllers.
|
|
- Prefer returning `JsonResource` or resource collections instead of raw models.
|
|
|
|
## Model Rules
|
|
|
|
- Models must stay inside their domain.
|
|
- Cross-domain relations are allowed when the dependency is explicit and necessary.
|
|
- Preserve existing table names and key mappings when the database uses legacy names.
|
|
|
|
## Naming Rules
|
|
|
|
- Domains use singular English names such as `Tenant` and `Product`.
|
|
- Namespace, folder, and class names must stay aligned.
|
|
- Route files should be named `api.php`.
|
|
|
|
## Current Areas and Modules
|
|
|
|
- `Core`: `Administrator`, `Auth`, `Authorization`, `Bootstrap`, `Client`,
|
|
`Menu`, `Staff`, `Tenant`.
|
|
- `Commerce`: `Cart`, `Catalog`, `Purchase`, `Sale`.
|
|
- `Ticketing`: `Desfile`, `Event`, `FiestaFutbolInfantil`, `Ticket`.
|
|
- `Shared`: `Attachable`, `Forms`, `Integration`, `Logging`, `MailTest`,
|
|
`Notification`, `StorageTest`, plus shared enums and rules.
|
|
|
|
## Notes For Future Changes
|
|
|
|
- New features should be added inside the corresponding domain first.
|
|
- Add new business features to the appropriate area under `app/Domains`.
|
|
- Keep generic reusable code in `app/Shared`; do not use it as a catch-all for
|
|
business features.
|
|
- Avoid placing new business code in `app/Http/Controllers` or `app/Models`.
|