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

```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
add composer-unused, comprehensive docs, and project restructure - Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks - Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists - Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services - Add Microsoft OIDC SSO, API token management, and user lifecycle features - Add swagger-ui vendor integration and OpenAPI spec - Add production Docker setup and bin/ scripts - Update composer dependencies, config, templates, and frontend assets throughout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-02-22 15:27:35 +01:00			`# Fehlerbehebung`

Global Boomarks 2026-03-14 21:45:58 +01:00			`Letzte Aktualisierung: 2026-03-14`
add composer-unused, comprehensive docs, and project restructure - Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks - Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists - Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services - Add Microsoft OIDC SSO, API token management, and user lifecycle features - Add swagger-ui vendor integration and OpenAPI spec - Add production Docker setup and bin/ scripts - Update composer dependencies, config, templates, and frontend assets throughout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-02-22 15:27:35 +01:00
			`## App reagiert nicht wie erwartet`

			`### Symptom`

			`UI zeigt alte Daten/Assets oder Verhalten wirkt stale.`

			`### Lösung`

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

major update 2026-03-04 15:56:58 +01:00			`## Erstdiagnose mit Doctor`

			`### Symptom`

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

			`### Lösung`

			```bash
fix(docs): resolve documentation drift and add missing content - Fix fictional SettingGateway/SettingService references with actual multi-gateway pattern (AdminSettingsService + domain-specific gateways) - Replace non-existent gridQueryLimitOffset()/gridQueryOrderDir() with actual gridParseFiltersFromSchemaFile() - Normalize bin/doctor.php references to canonical bin/console doctor - Add i18n_path contract to module manifest docs - Document module:validate and make:module CLI commands - Add APP_VENDOR_PHP_ISSUES_MODE env var to config reference - Remove invalid label field from notifications module permissions (violates manifest schema additionalProperties: false) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-03-25 19:15:53 +01:00			`docker compose exec php php bin/console doctor`
major update 2026-03-04 15:56:58 +01:00			```

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

add composer-unused, comprehensive docs, and project restructure - Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks - Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists - Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services - Add Microsoft OIDC SSO, API token management, and user lifecycle features - Add swagger-ui vendor integration and OpenAPI spec - Add production Docker setup and bin/ scripts - Update composer dependencies, config, templates, and frontend assets throughout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-02-22 15:27:35 +01:00			`## Login/API verhalten sich unerwartet`

			`### Symptom`

			`401/403 bei API trotz gültigem Token.`

			`### Checks`

weitere updates für instanzierbarkeit und sauberes testing 2026-02-24 08:49:40 +01:00			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`
add composer-unused, comprehensive docs, and project restructure - Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks - Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists - Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services - Add Microsoft OIDC SSO, API token management, and user lifecycle features - Add swagger-ui vendor integration and OpenAPI spec - Add production Docker setup and bin/ scripts - Update composer dependencies, config, templates, and frontend assets throughout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-02-22 15:27:35 +01:00
			`## 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`
			```

Global Boomarks 2026-03-14 21:45:58 +01:00			`### 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.`

add composer-unused, comprehensive docs, and project restructure - Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks - Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists - Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services - Add Microsoft OIDC SSO, API token management, and user lifecycle features - Add swagger-ui vendor integration and OpenAPI spec - Add production Docker setup and bin/ scripts - Update composer dependencies, config, templates, and frontend assets throughout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-02-22 15:27:35 +01:00			`## 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`