breadcrumb-the-shire/docs/reference-konventionen.md

# Konventionen (kurz und verbindlich)

Letzte Aktualisierung: 2026-03-09

## 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.
- Service-Instanzen in Actions/Helpern nur via `app(Foo::class)`.
- `new ...Factory()` nur im Composition Root (`web/index.php` + `lib/App/registerContainer.php`) oder in `*Factory.php`.
- In `lib/Service/**` außerhalb von `*Factory.php` keine direkten `new ...Factory()`, `new ...Service()`, `new ...Gateway()` oder `new ...Repository()`.
- Alte Service-Helper (`accessServicesFactory()`, `userServicesFactory()` usw.) nicht mehr verwenden.
- `pages/**/data().php` nur GET (`gridRequireGetRequest()`), Query-Normalisierung ausschließlich über `gridParseFilters(...)`.
- Für jede Liste ein `filter-schema.php` im selben Verzeichnis; `data().php`, `index().php` und `index(default).phtml` verwenden dieses Schema.
- Filter-Toolbar nur über `renderGridFilterToolbar(...)`, keine manuellen Filter-Inputs/-Selects.
- Client-Filterbindung nur über `gridFiltersFromSchema(...)` (kein inline `filters: [...]`).
- Für Listen gilt Filter UX 2.0: Quick Search sichtbar, restliche Filter im Drawer, aktive Filter-Chips.
- Search-only-Listen (nur Quick Search) verwenden keinen Drawer und bleiben im Live-Modus.
- `data-filter-overflow`, `data-filter-toggle` und `data-toolbar-toggle` sind Legacy und in Listen-Templates nicht mehr erlaubt.
- Listen-IDs nur als CSV-Parameter mit pluralem Key (`*_ids`), keine Alias-Fallbacks.

## 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/reference-frontend-css.md` und `/docs/reference-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: Browser-Smoke mit DevTools-Console (keine JS-Errors)