59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# Architektur-Kompass
|
|
|
|
Letzte Aktualisierung: 2026-02-23
|
|
|
|
Kurze, verbindliche Architekturübersicht für den aktuellen Stand.
|
|
|
|
## Begriffe (kurz)
|
|
|
|
- `Tenant`: Mandant, isolierter Daten- und Berechtigungsraum.
|
|
- `Department`: optionale organisatorische Untereinheit innerhalb eines Tenants.
|
|
- `Role`: Bündel von Berechtigungen.
|
|
- `Permission`: einzelne Berechtigung wie `users.view`.
|
|
- `Policy`: zentrale Autorisierungsregel für eine konkrete Fähigkeit.
|
|
- `Ability`: technischer Name einer Policy-Regel, z. B. `admin.users.edit.submit`.
|
|
- `AuthorizationDecision`: Ergebnis einer Policy (`allow/deny`, HTTP-Status, Fehlercode, Attribute).
|
|
- `Tenant-Scope`: Regel, ob ein User eine Ressource im Ziel-Tenant sehen oder ändern darf.
|
|
- `Request`: einzelner HTTP-Aufruf.
|
|
- `Action`: Datei unter `pages/**`, verarbeitet den Request.
|
|
- `Service`: Fachlogik unter `lib/Service/**`.
|
|
- `Repository`: SQL- und Mapping-Schicht unter `lib/Repository/**`.
|
|
- `UUID-first`: externe API gibt nur UUIDs aus, keine internen IDs.
|
|
- `Contract-Test`: Test für Architektur- und Schnittstellenregeln.
|
|
|
|
## Zielbild (Stand heute)
|
|
|
|
- Server-gerenderte App plus REST-API unter `/api/v1`.
|
|
- Strikte Multi-Tenant-Isolation.
|
|
- Zentrale Autorisierung über `AuthorizationService` und Policies.
|
|
- API-Verträge sind UUID-first.
|
|
|
|
## Request-Flow (verbindlich)
|
|
|
|
1. `web/index.php` lädt Bootstrap, Routing und Konfiguration.
|
|
2. Firewall, Session, Locale und Access-Control laufen.
|
|
3. Action unter `pages/**` nimmt Request an.
|
|
4. Action delegiert Fachlogik an Services.
|
|
5. Services nutzen Repositories für Datenzugriff.
|
|
6. Response wird als HTML, JSON oder Datei ausgegeben.
|
|
|
|
## Schichtregeln (MUSS)
|
|
|
|
- `pages/**`: Input, Auth/AuthZ, Service-Aufruf, Response. Keine duplizierte Business-Logik.
|
|
- `lib/Service/**`: Fachlogik und Orchestrierung. Keine Superglobals, keine Header/Redirect-Ausgabe.
|
|
- `lib/Repository/**`: SQL, Filter, Paging, Mapping. Keine HTTP-, Session- oder Policy-Logik.
|
|
- `templates/**`: nur Rendering.
|
|
|
|
## Sicherheits- und API-Regeln (MUSS)
|
|
|
|
- Autorisierung nur zentral über Policies.
|
|
- Tenant-Scope nicht lokal nachbauen.
|
|
- Scope-Denials pro Endpunkt-Semantik als `403` oder `404`.
|
|
- API-Fehler einheitlich: `error`, optional `errors`.
|
|
- OpenAPI wird bei API-Änderungen im selben Merge aktualisiert.
|
|
|
|
## Merge-Mindestchecks
|
|
|
|
- `docker compose exec php vendor/bin/phpunit`
|
|
- `docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress`
|