Yisroel Baum
a225433cec
Document Attainly-specific TDD, worktree, Laravel, database, and future Vue conventions adapted from the youngstartup workflow.
105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# Backend context
|
|
|
|
Read `ai/shared.md` first. This file covers backend-specific rules.
|
|
|
|
## Project context
|
|
|
|
**Stack:** PHP 8.4, Laravel 13, Inertia Laravel, PHPUnit, Larastan, Composer.
|
|
|
|
**Location:** `backend/`.
|
|
|
|
The application is still close to the Laravel starter structure. Do not
|
|
introduce a domain architecture, repository layer, service layer, or other
|
|
abstraction before the codebase and requested behavior justify it. Match
|
|
existing Laravel conventions and inspect similar code before adding a new
|
|
pattern.
|
|
|
|
## Laravel patterns
|
|
|
|
- Keep controllers thin. Put reusable business behavior in an appropriately
|
|
named application or domain class once the behavior warrants extraction.
|
|
- Use dedicated request validation rather than validating substantial payloads
|
|
inline in controllers.
|
|
- Let unexpected exceptions reach Laravel's exception handler. Catch only
|
|
exceptions that can be handled meaningfully at the current boundary.
|
|
- Use Eloquent relationships and query scopes consistently rather than
|
|
duplicating query fragments.
|
|
- Avoid speculative interfaces and abstractions with only one trivial
|
|
implementation.
|
|
- Routes currently use Inertia, but the Vue client has not been scaffolded.
|
|
Do not add placeholder frontend assets as part of unrelated backend work.
|
|
|
|
## Tests
|
|
|
|
- Follow the existing PHPUnit organization under `tests/Unit/` and
|
|
`tests/Feature/`.
|
|
- Prefer `PHPUnit\Framework\TestCase` when a test only exercises plain PHP.
|
|
- Extend `Tests\TestCase` only when the test needs Laravel's container,
|
|
facades, database, routing, or HTTP kernel.
|
|
- HTTP feature tests extend `Tests\TestCase`.
|
|
- Use `RefreshDatabase` when a test reads or writes database state.
|
|
- Assert behavior at the appropriate seam:
|
|
- Unit tests cover isolated business behavior and edge cases.
|
|
- Feature tests cover routing, middleware, validation, persistence, and
|
|
response shape.
|
|
- Do not duplicate every business branch through the HTTP layer when unit
|
|
coverage already proves it. Feature tests should focus on wiring and the
|
|
public contract.
|
|
|
|
## Test database
|
|
|
|
- Development and runtime use PostgreSQL through the local Unix socket.
|
|
- PHPUnit intentionally uses SQLite `:memory:` as configured in
|
|
`phpunit.xml`.
|
|
- Feature tests are self-contained and do not require the process-compose
|
|
PostgreSQL service.
|
|
- Never point `RefreshDatabase` tests at the development PostgreSQL database.
|
|
- Keep mail set to the PHPUnit `array` transport unless a test explicitly
|
|
exercises a real mail integration.
|
|
|
|
## PHP rules
|
|
|
|
- Put imports at the top of the file. Do not use inline fully qualified class
|
|
names when a normal `use` statement is clearer.
|
|
- Do not use arrow functions. Use regular anonymous functions.
|
|
- Do not add default values to function or constructor parameters. Pass every
|
|
argument explicitly, including nullable arguments.
|
|
- Use descriptive names for classes, methods, parameters, and local
|
|
variables.
|
|
- Document exceptions with `@throws` when a caller is expected to handle
|
|
them.
|
|
|
|
## Seeders
|
|
|
|
- Keep `DatabaseSeeder` as the orchestrator.
|
|
- Split substantial seed data into one seeder per domain concept and invoke
|
|
them in dependency order.
|
|
- Do not add production repository or model APIs solely to make seeding
|
|
convenient.
|
|
- Use existing lookup methods for cross-seeder relationships. When a group of
|
|
records only makes sense together, keep them in one seeder and retain local
|
|
references.
|
|
|
|
## Migrations
|
|
|
|
- Attainly is not in production yet.
|
|
- While no production database exists, edit the original `create_*` migration
|
|
when changing a table instead of accumulating follow-up alter migrations.
|
|
- Keep one migration file per table during this pre-production phase.
|
|
- Rebuild the development database with:
|
|
|
|
```sh
|
|
php artisan migrate:fresh --seed
|
|
```
|
|
|
|
- Once a production database exists, replace this policy with additive,
|
|
forward-only migrations.
|
|
|
|
## Before completing backend work
|
|
|
|
- Run the focused test during development.
|
|
- Run `php artisan test` before completion.
|
|
- Run the Composer lint and static-analysis scripts when their dependencies
|
|
are available.
|
|
- Fix failures caused by the change. Report unrelated baseline failures
|
|
precisely rather than hiding them or expanding scope without authorization.
|