---
apply: always
---

<!-- AUTOGENERATED: Run `node scripts/sync-ai-workflow.mjs --write`. -->

# Backend Route Rules

These rules apply to files under `services/nginx/app/routes` and the classes they call.

1. Keep route handlers thin: validate input, enforce permissions, call domain code, and write the response.
2. Default to protected endpoints. Use the existing authentication and permission helpers instead of ad hoc access checks.
3. Add or update backend tests in the `php1` container whenever route behavior changes.
4. Update `openapi.yaml` whenever paths, parameters, request bodies, response envelopes, or permissions change.
5. Prefer deterministic route tests and avoid live external integrations in route coverage.
6. Use concise API errors and keep sensitive implementation details out of the response body.
7. When a change touches department, order, or subuser authorization, cover both the allow path and the deny path.

Canonical workflow reference: `.ai-workflow/workflow.md`.