breadcrumb-the-shire/docs/howto-fehlerbehebung.md

Fehlerbehebung

Letzte Aktualisierung: 2026-03-14

App reagiert nicht wie erwartet

Symptom

UI zeigt alte Daten/Assets oder Verhalten wirkt stale.

Lösung

docker compose restart php nginx

Erstdiagnose mit Doctor

Symptom

Unklar, ob das Problem aus ENV, DB, Storage, RBAC oder Scheduler kommt.

Lösung

docker compose exec php sh -lc "php bin/doctor.php"

Bei FAIL zuerst diese Punkte beheben, danach erneut ausführen.

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

Hinweis (Hard Cut 2026-03-14)

Das Update db/updates/2026-03-14-user-bookmarks.sql entfernt user_saved_filters bewusst ohne Migration nach user_bookmarks. Zusätzlich wurde der alte Bookmark-Icon-Ansatz pro Eintrag entfernt: Icons gelten nur noch auf Gruppenebene (user_bookmark_groups.icon), bestehende Bookmark-Icons werden nicht übernommen. Wenn gespeicherte Filter noch benötigt werden, vor dem Update ein DB-Backup erstellen.

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