# CLQMS Style and Conventions
## PHP and Naming
- PHP 8.1+, PSR-4 autoloading (`App\\` => `app/`, `Config\\` => `app/Config/`).
- Follow PSR-12 where applicable.
- Class names: PascalCase.
- Method names: camelCase.
- Properties: legacy snake_case and newer camelCase coexist.
- Constants: UPPER_SNAKE_CASE.
- DB tables: snake_case; many DB columns are legacy PascalCase.
- JSON fields in API responses often use PascalCase for domain fields.

## Controller Pattern
- Controllers should handle HTTP concerns and delegate to model/service logic.
- Avoid embedding DB query logic directly inside controllers.
- Use `ResponseTrait` and consistent JSON envelope responses.

## Response Pattern
- Success: `status=success`, plus message/data.
- Error: structured error response with proper HTTP status codes.
- Empty strings may be normalized to `null` by custom response behavior.

## DB and Data Handling
- Prefer CodeIgniter Model/Query Builder usage.
- Use UTC helper conventions for datetime handling.
- Multi-table writes should be wrapped in transactions.
- For nested entities/arrays, extract and handle nested payloads carefully before filtering and persistence.

## Error Handling
- Use try/catch for JWT and external operations.
- Log errors with `log_message('error', ...)`.
- Return structured API errors with correct status codes.

## Testing Convention
- PHPUnit tests in `tests/`.
- Test naming: `test<Action><Scenario><ExpectedResult>`.
- Typical status expectation: 200 (GET/PATCH), 201 (POST), 400/401/404/500 as appropriate.

## API Docs Rule (Critical)
- Any controller/API contract change must update corresponding OpenAPI YAML files under:
  - `public/paths/*.yaml`
  - `public/components/schemas/*.yaml`
  - optionally `public/api-docs.yaml` if references/tags change
- Rebuild docs bundle after YAML updates.