further rework to the documentation

docs/ops/dr-storage-issues.md

@@ -0,0 +1,74 @@
+---
+title: DR-Playbook – Storage-Probleme (Hot/Archive)
+sidebar_label: DR – Storage
+---
+
+Dieses Playbook beschreibt, wie du vorgehst, wenn es Probleme mit dem Medien‑Storage gibt – z.B. Hot‑Storage voll, Archivierung bleibt hängen oder viele Assets im Status `failed`.
+
+## 1. Symptome & erste Checks
+
+Typische Symptome:
+
+- Gäste können keine Fotos mehr hochladen (Fehlermeldungen im Upload‑Flow).
+- Tenant Admins sehen „fehlende Medien“ oder sehr langsame Galerien.
+- `event_media_assets` enthält viele Einträge mit Status `pending` oder `failed`.
+- Logs enthalten Hinweise auf fehlgeschlagene Archivierungen oder fehlende Dateien.
+
+Erste Checks:
+
+- Storage‑Usage der Hot‑Volumes/Buckets prüfen (Docker‑Volume, S3‑Dashboard o.ä.).
+- `EventMediaAsset`‑Status stichprobenartig prüfen (`hot`, `archived`, `pending`, `failed`).
+- Queue‑Längen und Fehler in `media-storage` und `media-security` via Horizon und Logs.
+
+## 2. Hot-Storage voll oder kurz vor Limit
+
+1. **Warnungen bestätigen**
+   - System‑/Provider‑Warnungen (z.B. 90 % voll) bestätigen.
+   - Prüfen, ob `storage:monitor` oder ähnliche Kommandos bereits Alerts ausgelöst haben.
+2. **Sofortmaßnahmen**
+   - Archivierung priorisieren: sicherstellen, dass `storage:archive-pending` regelmäßig läuft und die `media-storage`‑Queue abgearbeitet wird.
+   - Temporäre Limits erhöhen, falls Provider dies erlaubt (z.B. S3‑Bucket praktisch „unbegrenzt“ vs. lokaler Disk).
+3. **Aufräumen**
+   - Alte Caches/Thumbnails, die problemlos neu generiert werden können, ggf. gezielt löschen.
+   - Keine unüberlegten `rm -rf` Aktionen auf dem Storage – immer mit klarer Strategie arbeiten.
+
+## 3. Archivierung hängt oder schlägt häufig fehl
+
+1. **Queue-Status prüfen**
+   - `media-storage` Queue‑Länge, Failed Jobs in Horizon prüfen.
+   - Log‑Channel `storage-jobs` nach Fehlermeldungen durchsuchen.
+2. **Fehlerbilder auswerten**
+   - Typische Ursachen:
+     - Netzwerk‑/Credential‑Probleme beim Zugriff auf den Archiv‑Bucket.
+     - Zeitüberschreitungen bei sehr großen Medien.
+     - Inkonsistente `EventMediaAsset`‑Einträge (Pfad nicht mehr vorhanden, falscher Disk‑Key).
+3. **Abhilfe**
+   - Netzwerk/Credentials fixen (z.B. S3‑Keys, Endpoints, Rechte).
+   - Problematische Assets gezielt in den Logs identifizieren und manuell nachziehen (Kopie auf Archive‑Disk, Status auf `archived` setzen, Fehler‑Feld leeren).
+   - Wenn viele Assets betroffen sind, lieber ein dediziertes Skript/Job bauen als ad‑hoc SQL.
+
+## 4. Fehlende oder beschädigte Medien-Dateien
+
+Wenn `EventMediaAsset`‑Einträge existieren, die zu nicht mehr vorhandenen Dateien zeigen:
+
+1. **Umfang ermitteln**
+   - Stichproben auf Basis der Fehlerlogs oder per Batch‑Check (z.B. ein Artisan‑Command, das `exists()` prüft).
+2. **Backup-Sicht**
+   - Prüfen, ob die Dateien noch im Backup vorhanden sind (Hot‑/Archive‑Backups).
+3. **Wiederherstellung**
+   - Fehlende Dateien an den erwarteten Pfad im Storage kopieren (Hot oder Archive).
+   - `EventMediaAsset`‑Status und Timestamps ggf. aktualisieren (`hot` vs. `archived`).
+
+Wenn keine Backups existieren, bleibt nur, die betroffenen Assets sauber als „nicht mehr verfügbar“ zu kennzeichnen und die Nutzer entsprechend zu informieren.
+
+## 5. Nach einem Storage-Incident
+
+- **Monitoring schärfen**
+  - Schwellwerte in `storage-monitor` anpassen (Warnung/Kritisch), Alerts für Queues/Storage erweitern.
+- **Kapazitätsplanung**
+  - Erkenntnisse über Medienwachstum nutzen, um frühzeitig auf größere Volumes/Buckets oder häufigere Archivierung umzusteigen.
+- **Dokumentation**
+  - Incident und Maßnahmen in `docs/process/changes/*` dokumentieren.
+  - Dieses Playbook aktualisieren, wenn neue Muster entdeckt wurden.
+
+Dieses Playbook ist eng mit `docs/ops/media-storage-spec.md` und `docs/ops/monitoring-observability.md` verknüpft. Nutze diese Dokumente für Detailinformationen zu Queues, Thresholds und Storage‑Targets.