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

# Fehlerbehebung

Letzte Aktualisierung: 2026-04-29

## Schema scheint veraltet nach `git pull`

### Symptom

Nach einem Pull schlagen Queries fehl, weil eine Spalte/Tabelle fehlt — oder der Doctor meldet inkonsistentes Schema.

### Lösung

```bash
docker compose exec php php bin/console db:migrate --status   # zeigt was fehlt
docker compose exec php php bin/console module:sync           # wendet alles an (db:migrate + module:migrate + ...)
```

`db:migrate` wendet idempotente Updates aus `db/updates/*.sql` an und trackt sie in `core_migrations`. Auch nach manuellem `mariadb < db/updates/...sql` sicher: jeder Lauf ist idempotent.

## App reagiert nicht wie erwartet

### Symptom

UI zeigt alte Daten/Assets oder Verhalten wirkt stale.

### Lösung

```bash
docker compose restart php nginx
```

## Erstdiagnose mit Doctor

### Symptom

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

### Lösung

```bash
docker compose exec php php bin/console doctor
```

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:

```bash
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

```bash
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

```bash
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