docs: restructure docs to diataxis and finalize DOCS-RESTRUCTURE-001

docs/howto-fehlerbehebung.md

@@ -0,0 +1,98 @@
+# Fehlerbehebung
+
+Letzte Aktualisierung: 2026-03-06
+
+## 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 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:
+
+```bash
+docker compose restart php
+```
+
+## 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