further rework to the documentation

docs/ops/howto-photobooth-no-photos.md

@@ -0,0 +1,87 @@
+---
+id: howto-photobooth-no-photos
+title: How-to – Photobooth lädt keine Fotos
+sidebar_label: Photobooth lädt nichts
+---
+
+Dieses How‑to beschreibt, wie du vorgehst, wenn ein Tenant meldet, dass von der Photobooth keine Fotos im Event ankommen.
+
+## 1. Problem eingrenzen
+
+Fragen an den Tenant:
+
+- Welcher Event ist betroffen? (Event‑ID oder Titel).
+- Wird im Tenant‑Admin unter „Fotobox-Uploads“ angezeigt, dass die Photobooth aktiviert ist?
+- Sieht der Photobooth‑Operator offensichtliche Fehler am Gerät (z.B. FTP‑Fehler, Timeout)?
+- Seit wann kommt nichts mehr an? (Zeitfenster)
+
+Diese Infos helfen dir, zwischen Konfigurations‑, FTP‑ oder Ingest‑Problem zu unterscheiden.
+
+## 2. Konfiguration im Admin prüfen
+
+1. Im Tenant-Admin:
+   - Den betroffenen Event öffnen.
+   - Prüfen, ob die Photobooth‑Funktion für diesen Event aktiviert ist.
+2. Wenn Photobooth deaktiviert ist:
+   - Tenant bitten, sie im UI zu aktivieren (dies triggert die Provisionierung und Credentials).
+   - Danach erneut testen, ob Uploads ankommen.
+
+## 3. FTP-/Control-Service überprüfen
+
+Siehe auch `docs/ops/photobooth/control_service.md` und `docs/ops/photobooth/ops_playbook.md`.
+
+1. **FTP-Erreichbarkeit**
+   - Host/Port aus den Photobooth‑Einstellungen entnehmen.
+   - Testverbindung (z.B. über lokales FTP‑Tool oder `nc`/`telnet`) herstellen:
+     - Port (z.B. 2121) erreichbar?
+2. **Credentials validieren**
+   - Prüfen, ob Username/Passwort im Tenant‑Admin zu den Control‑Service‑Daten passen.
+   - Bei Verdacht auf Fehler:
+     - Im Admin die Zugangsdaten neu generieren lassen.
+     - Tenant/Photobooth‑Team informieren, dass sie die neuen Credentials konfigurieren müssen.
+
+## 4. Ingest-Service & Scheduler prüfen
+
+Die Photobooth legt Dateien zunächst in einem Import‑Pfad ab, der dann vom Ingest‑Service verarbeitet wird.
+
+1. **Import-Verzeichnis prüfen**
+   - Pfad: üblicherweise `storage/app/photobooth/{tenant}/{event}` (siehe `docs/ops/photobooth/README.md`).
+   - In den Logs kontrollieren, ob neue Dateien dort landen.
+2. **Ingest-Command**
+   - Sicherstellen, dass `photobooth:ingest` regelmäßig läuft (Scheduler/Cron):
+     ```bash
+     php artisan photobooth:ingest --max-files=100
+     ```
+   - Optional: für einen konkreten Event:
+     ```bash
+     php artisan photobooth:ingest --event=EVENT_ID --max-files=50 -vv
+     ```
+   - Logs auf Hinweise prüfen:
+     - Fehler beim Lesen der FTP‑Dateien.
+     - Probleme beim Schreiben in den Hot‑Storage.
+3. **Queues**
+   - Verifizieren, dass relevante Queues laufen (falls Ingest Jobs dispatcht).
+
+## 5. Typische Fehlerbilder & Lösungen
+
+- **FTP erreicht, aber Import-Verzeichnis bleibt leer**
+  - Photobooth‑Software schreibt nicht an den erwarteten Pfad → Pfad in der Photobooth‑Konfiguration mit den Angaben aus `PHOTOBOOTH_IMPORT_ROOT` abgleichen.
+  - Evtl. Berechtigungsproblem im FTP‑Container (Perms/Ownership).
+- **Import-Verzeichnis gefüllt, aber nichts im Event**
+  - `photobooth:ingest` läuft nicht oder bricht ab:
+    - Scheduler prüfen (`scheduler`‑Service in Docker/Dokploy).
+    - Kommando manuell ausführen und Fehler analysieren.
+- **Fotos tauchen mit großer Verzögerung auf**
+  - Ingest läuft zu selten (Cron/Intervalle zu groß).
+  - Events haben hohe Medienlast → `--max-files` erhöhen oder Ingest häufiger anstoßen.
+
+## 6. Kommunikation mit dem Tenant
+
+- Sobald Ursache und Fix klar sind:
+  - Tenant informieren, ob es ein Konfig‑, Netzwerk‑ oder Ingest‑Problem war.
+  - Falls nötig, dem Photobooth‑Team neue Credentials/Anweisungen zukommen lassen.
+- Falls einige Dateien irreversibel verloren gegangen sind:
+  - Transparent kommunizieren und ggf. Kulanzlösungen (z.B. Gutschrift) über Finance/Success abstimmen.
+
+Nutze für tiefere Analysen die ausführlicheren Playbooks in `docs/ops/photobooth/ops_playbook.md`.
+