further rework to the documentation

docs/ops/howto-guest-upload-failing.md

@@ -0,0 +1,83 @@
+---
+id: howto-guest-upload-failing
+title: How-to – Gäste können nicht hochladen
+sidebar_label: Gäste können nicht hochladen
+---
+
+Dieses How‑to beschreibt, wie du vorgehst, wenn Gäste melden, dass sie keine Fotos mehr hochladen können (Fehler im Upload‑Flow oder „hängenbleibende“ Uploads).
+
+## 1. Problem eingrenzen
+
+Fragen an den Tenant/Support:
+
+- Betrifft es **alle** Gäste oder nur einzelne?
+- Betrifft es **alle** Events oder nur ein bestimmtes Event?
+- Welche Fehlermeldung erscheint im Guest‑Frontend (so genau wie möglich, gerne mit Screenshot)?
+- Seit wann tritt das Problem auf? (Zeitfenster)
+
+Diese Informationen bestimmen, ob du in Richtung API/Rate‑Limit, Storage/Queues oder Event‑Konfiguration schauen musst.
+
+## 2. Basischecks – API & App
+
+1. **Public-API Status**
+   - Teste manuell einen Upload gegen ein Test‑Event oder reproduziere das Problem mit dem betroffenen Join‑Token.
+   - Achte auf HTTP‑Statuscodes im Browser‑Network‑Tab (4xx vs. 5xx).
+2. **App- / Deployment-Status**
+   - Prüfe in Docker/Dokploy, ob App/Queue/Redis/DB‑Container gesund sind.
+   - Schaue in `storage/logs/laravel.log` nach offensichtlichen Exceptions rund um das gemeldete Zeitfenster.
+
+Wenn die Public‑API generell 5xx liefert, greift eher das Public‑API‑Incident‑Playbook (`docs/ops/deployment/public-api-incident-playbook.md`).
+
+## 3. Queues & Upload-Health
+
+Wenn das Problem hauptsächlich Uploads betrifft (andere Funktionen laufen):
+
+1. **Queue-Längen prüfen**
+   - In Horizon:
+     - `media-storage`, `media-security` und ggf. `notifications` Queue‑Längen ansehen.
+   - In Logs:
+     - Warnungen aus `storage:check-upload-queues` oder `storage-jobs` suchen.
+2. **Upload-Health-Command**
+   - Sicherstellen, dass `storage:check-upload-queues` regelmäßig läuft (Cron / Scheduler).
+   - Manuell ausführen (in der App‑Container‑Shell):
+     ```bash
+     php artisan storage:check-upload-queues
+     ```
+   - Ausgaben/Logs prüfen:
+     - Meldungen zu „stalled“ Uploads, Events mit dauerhaft vielen Pending‑Assets.
+
+## 4. Storage & Limit-Probleme
+
+1. **Hot-Storage-Füllstand**
+   - Prüfen, ob das Storage‑Volume/Bucket nahe an 100 % ist (siehe `docs/ops/dr-storage-issues.md`).
+   - Wenn ja:
+     - Archivierung beschleunigen (`storage:archive-pending` verifizieren).
+     - Kurzfristig Speicher vergrößern oder Caches aufräumen.
+2. **Paket-/Limit-Prüfungen**
+   - Wenn nur bestimmte Events betroffen sind:
+     - Paket‑Limits des Events prüfen (z.B. max_photos/max_guests).
+     - Event‑Status (abgelaufen/archiviert?) prüfen.
+   - Logs können Fehlercodes liefern wie „photo_limit_exceeded“ – diese deuten auf bewusst ausgelöste Limit‑Sperren hin, nicht auf technische Fehler.
+
+## 5. Typische Muster & Gegenmaßnahmen
+
+- **Hohe Fehlerrate beim Upload (5xx)**
+  - Hinweis auf API‑/Backend‑Problem:
+    - Siehe Public‑API‑Runbook und App‑Logs (Datenbank‑/Redis‑Fehler, Timeouts).
+- **Uploads bleiben „ewig“ auf „wird verarbeitet“**
+  - Queues laufen nicht oder `media-storage`/`media-security` steckt fest:
+    - Horizon prüfen, ob Worker‑Container laufen.
+    - Ggf. Worker neu starten und Failed Jobs analysieren.
+- **Nur ein Event betroffen, andere funktionieren**
+  - Meist Limit‑ oder Konfig‑Thema (Paket voll, Galerie abgelaufen, Event deaktiviert).
+  - Tenant‑Admin‑UI prüfen: Event‑Status, Paket‑Status, Data Lifecycle Einstellungen.
+
+## 6. Kommunikation
+
+- **An Tenant/Support zurückmelden**:
+  - Was war die Ursache? (z.B. Paket‑Limit, temporäre Überlastung, Storage‑Knappheit).
+  - Was wurde getan? (z.B. Paket angepasst, Queues neu gestartet, Storage erweitert).
+  - Ob und wie der Tenant/gäste weiteres tun müssen (z.B. Seite neu laden, später erneut probieren).
+
+Für tiefere Ursachen rund um Storage siehe `docs/ops/media-storage-spec.md` und `docs/ops/dr-storage-issues.md`.
+