api/.aiassistant/rules/Creating and securing routes.md

apply

apply
always

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.