fotospiel-app/docs/ops/incidents-major.md

title, sidebar_label

title	sidebar_label
Major Incidents & Eskalation	Major Incidents

Diese Seite beschreibt, wie du bei größeren Störungen (SEV‑1/SEV‑2) vorgehst. Sie ergänzt die spezifischen Runbooks (Public API, Medien‑Pipeline, Photobooth) um einen einheitlichen Rahmen.

1. Incident-Klassifikation

• SEV‑1 (kritisch)
  • Gäste können nicht mehr hochladen ODER keine Events/Galerien mehr öffnen.
  • Tenant Admins können sich nicht einloggen oder keine Kernaktionen ausführen (Events verwalten, Medien moderieren).
  • Datenverlust oder potenzieller Datenverlust (z.B. Löschjob auf falscher Storage‑Ebene).
• SEV‑2 (hoch)
  • Teilweise Degradation (z.B. Photobooth‑Uploads hängen, Public‑API stark verlangsamt, eine Region betroffen).
  • Kritische Background‑Jobs (Archivierung, AV/EXIF‑Scans, Zahlungs‑Webhooks) stauen sich, ohne dass Gäste sofort komplett blockiert sind.
• SEV‑3 (mittel)
  • Einzelne Features gestört (Notification‑Center, Join‑Token‑Analytics, einzelne Admin‑Views).
  • Workaround möglich (z.B. manuelle Nacharbeit durch Support).

Wichtig: Jede Störung, die einen zahlenden Eventkunden am Tag des Events blockiert, sollte mindestens als SEV‑2, ggf. als SEV‑1 eingeordnet werden.

2. Erstmaßnahmen (Triage)

1. Scope bestimmen

• Welche Benutzer sind betroffen? (Alle Gäste, einzelne Tenants, nur Photobooth, nur Admins?)
• Betrifft es nur eine Umgebung (staging vs. production)?

2. Schnell-Checks
   • Status von App, Queue, Redis, DB (Docker/Dokploy‑Übersicht prüfen).
   • Horizon/Queues: sind relevante Queues leer, wachsend, „stuck“? Gibt es viele Failed Jobs?
   • Logs für relevante Kanäle: storage/logs/laravel.log, spezielle Channels wie storage-jobs, notifications, billing, Nginx/Proxy‑Logs.
   • Monitoring: externe Uptime‑Checks / Dashboards (z.B. Public‑API Latenz, Error‑Rate).
3. Einordnung & Eskalation

• SEV‑1/2: On‑Call informieren (Pager/Chat), Incident‑Kanal im Teamchat eröffnen.
• SEV‑3: Im Issue‑Tracker erfassen, ggf. gebündelt mit anderen Findings.

Nutze bei Public‑API‑Problems zusätzlich das docs/ops/deployment/public-api-incident-playbook.md.

3. Standard-Runbooks nach Bereich

• Public API / Gast-Zugriff
  • Siehe docs/ops/deployment/public-api-incident-playbook.md.
  • Typische Auslöser: Peaks, Abuse, externe Integrationen, Ratenlimits.
• Medien-Pipeline / Uploads
  • Siehe docs/ops/media-storage-spec.md und docs/ops/guest-notification-ops.md.
  • Fälle: Uploads bleiben im Pending, Archivjobs laufen nicht, Speicherkapazität erreicht, Gäste bekommen „Uploads hängen noch…“.
• Photobooth
  • Siehe docs/ops/photobooth/ops_playbook.md.
  • Fälle: FTP nicht erreichbar, Ingest nicht laufend, falsche Credentials, Security‑Vorfälle.
• Abrechnung & Billing
  • Siehe docs/ops/billing-ops.md.
  • Fälle: Paddle/RevenueCat‑Webhook‑Fehler, falsche Paket‑Zustände, doppelte/fehlende Buchungen.

Dieses Dokument verweist immer nur auf die jeweils tieferen Runbooks – bei konkreten Problemen gehst du dort in die Details.

4. Kommunikation

• Intern (Team)
  • Eröffne einen dedizierten Incident‑Thread im Chat (mit Zeitstempel, SEV‑Level, Kurzbeschreibung).
  • Halte dort Statusupdates fest (z.B. „17:05 – Upload‑Queue entstaut, weitere Beobachtung 30 min“).
  • Notiere bewusst Entscheidungen (z.B. „19:10 – Feature X temporär deaktiviert“, „19:25 – Rollback auf vorheriges Release“).
• Extern (Kunden)
  • Ab SEV‑2: Überlege einen kurzen Statushinweis (Status‑Seite oder manuelle Kommunikation an direkt betroffene Tenants).
  • Bei Incidents während Events: Koordiniere mit Success/Support, um proaktiv auf Tenant Admins zuzugehen.

TODO: Falls du eine Status‑Seite oder automatisierte E‑Mails hast, dokumentiere hier, wie und wann sie ausgelöst werden.

5. Nachbereitung (Postmortem)

Nach einem SEV‑1/2 Incident:

1. Fakten sammeln (Timeline, betroffene Tenants/Events, konkrete Auswirkungen).
2. Ursache (Root Cause) möglichst präzise identifizieren – auch dann, wenn direkt „nur“ Symptome gefixt wurden.
3. Kurzfristige Maßnahmen (Hotfixes, Konfig‑Anpassungen, zusätzliche Checks).
4. Langfristige Maßnahmen – sollten als Epics/Tasks in docs/process/todo/* bzw. docs/process/changes/* landen (inkl. Link zum Incident).
5. Dokumentation aktualisieren

• Relevante Runbooks (dieses Dokument, Public‑API‑Runbook, Storage‑Spec, Billing‑Ops, etc.) mit neuen Learnings ergänzen.

Ziel ist, dass die Time‑to‑Detect und Time‑to‑Resolve für ähnliche Probleme in Zukunft sinkt.