breadcrumb-the-shire/docs/fehlerbehebung.md

Fehlerbehebung

Letzte Aktualisierung: 2026-02-23

App reagiert nicht wie erwartet

Symptom

UI zeigt alte Daten/Assets oder Verhalten wirkt stale.

Lösung

docker compose restart php nginx

Login/API verhalten sich unerwartet

Symptom

401/403 bei API trotz gültigem Token.

Checks

1. Für geschützte Endpunkte Authorization Header korrekt gesetzt (Bearer <selector:secret>)
2. Ausnahme: /api/v1/auth/login ist public und benötigt keinen Bearer-Header
3. Token nicht revoked/abgelaufen
4. Token hat erforderliche Permission
5. Bei tenant-scoped Token: Zugriff nur auf passende Tenant-Ressourcen

Migration oder Schema-Probleme

Symptom

Neue Felder/Features fehlen lokal.

Lösung

1. Aktuelles Schema in db/init/init.sql prüfen
2. Für Bestandsumgebung idempotentes SQL-Update ausführen
3. Danach Container neu starten:

docker compose restart php

i18n Fehler

Symptom

Fehlende Translation-Keys oder Mixed-Language UI.

Lösung

docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/I18n/TranslationKeysTest.php

PHPStan/Tests schlagen plötzlich fehl

Symptom

Fehler nach Refactor, obwohl Seite lädt.

Lösung

docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php

Dann gezielt betroffene Datei/Service prüfen.

Swagger UI lädt ungestylt oder inkonsistent

Symptom

API docs sehen nicht nach App-Theme aus.

Lösung

1. Prüfen, dass Buffer::set('style_groups', json_encode(['api-docs'])) gesetzt ist
2. Prüfen, dass css/vendor-overrides/swagger-ui.css über config/assets.php eingebunden ist
3. Hard-Reload im Browser