breadcrumb-the-shire/docs/konventionen.md

Konventionen (kurz und verbindlich)

Letzte Aktualisierung: 2026-02-23

1) Code

• Kleine, fokussierte Änderungen statt Misch-Commits.
• Kein toter Code, keine ungenutzten Helpers.
• ASCII als Standard, Unicode nur wenn Datei es bereits nutzt.

2) Schichten

• SQL nur in lib/Repository/**.
• Fachlogik nur in lib/Service/**.
• pages/** bleibt dünn: Input, Auth/AuthZ, Service-Aufruf, Response.
• Neue Domain-Logik als Instanz-Service mit Factory-Verdrahtung.

3) Autorisierung

• Nur zentrale Policy-Abilities nutzen.
• Keine verteilten userHas(...)-Checks als Hauptlogik.
• Tenant-Scope nicht in Templates oder JavaScript nachbauen.

4) API

• UUID-first für externe Ressourcen.
• Interne IDs nicht nach außen geben.
• Fehlerantworten einheitlich halten (error, optional errors).
• OpenAPI bei jeder API-Änderung im selben Merge aktualisieren.

5) Frontend

• Templates nur für Rendering.
• UI-Texte über t('...').
• Strukturregeln in docs/frontend-css.md und docs/frontend-javascript.md.

6) Mindestchecks vor Merge

• docker compose exec php vendor/bin/phpunit
• docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
• bei JS-Änderungen: npx eslint web/js