# Emergency Guide / Notfall-Leitfaden - Dosenhub V3

Nutze diesen Leitfaden, wenn während des Betriebs oder beim Starten von Dosenhub V3 Probleme auftreten.

## 1. Problem: Dosenhub startet nicht

### Symptom:
Die Konsole schließt sich sofort nach dem Ausführen von `start-dosenhub.bat` oder `npm run dev` stürzt mit Fehlern ab.

### Lösungsschritte:
1. **Node.js-Installation prüfen:**
   Öffne eine Shell und führe `node -v` aus. Wenn der Befehl unbekannt ist, lade Node.js neu herunter und installiere es.
2. **Abhängigkeiten neu installieren:**
   Führe im Dosenhub-Ordner aus:
   ```bash
   npm install
   ```
3. **Smoke-Test ausführen:**
   Führe den internen Selbsttest aus, um Fehler in den Konfigurationsdateien oder Datenbankstrukturen zu finden:
   ```bash
   npm run smoke
   ```
4. **Fehlende Konfigurationsdatei:**
   Wenn `config/app.config.json` beschädigt oder gelöscht wurde, kopiere die Vorlage `config/app.config.example.json` und benenne sie um.

## 2. Problem: Overlay lädt nicht in OBS

### Symptom:
Die Browserquelle in OBS bleibt schwarz oder zeigt eine Fehlermeldung.

### Lösungsschritte:
1. **Dosenhub-Server prüfen:**
   Verifiziere, dass Dosenhub gestartet ist und das Dashboard unter [http://127.0.0.1:3000/](http://127.0.0.1:3000/) geladen werden kann.
2. **URL-Pfade prüfen:**
   Führe `npm run stream:urls` aus und vergleiche die kopierte URL exakt mit dem Pfad in der OBS-Browserquelle.
3. **Zwei-PC-Setup / IP geändert:**
   Wenn OBS auf einem separaten Streaming-PC läuft, prüfe die LAN-IP deines Gaming-PCs. Trage die korrekte IP in `config/app.config.json` unter `lanBaseUrl` ein (z. B. `http://192.168.1.100:3000`) und starte Dosenhub neu.

## 3. Problem: Sound wird nicht abgespielt

### Symptom:
Ein Zuschauer löst im Chat einen Sound aus (z. B. `!sound jumpscare`), der Kauf wird verbucht und im Livefeed gelistet, aber es ertönt kein Audio.

### Lösungsschritte:
1. **Wichtige Sound-Regel beachten:**
   Dosenhub spielt **keine** Sounds selbst ab. Es besitzt keine Audio-Engine. Die Sounds werden ausschließlich über streamer.bot auf dem Gaming-PC abgespielt.
2. **streamer.bot-Verbindung prüfen:**
   Prüfe das streamer.bot-Widget auf dem Dashboard. Wenn es "Getrennt" anzeigt, starte streamer.bot.
3. **Outbox prüfen:**
   Navigiere zur Outbox-Verwaltung unter `/bot-messages`. Wenn dort Nachrichten mit dem Status `failed` gelistet sind, klicke auf "Retry". Prüfe, ob die Webhook-URL in `app.config.json` unter `botMessages.outbound.url` mit streamer.bot übereinstimmt.
4. **streamer.bot Actions prüfen:**
   Stelle sicher, dass in streamer.bot die Action für den Sound-Key (z. B. `jumpscare`) angelegt und funktionsfähig ist.

## 4. Problem: Falsche Daten nach Migration

### Symptom:
Nach einem Import aus Staging fehlen Daten, Punktekonten sind fehlerhaft oder es kam zu Konflikten.

### Lösungsschritte:
1. **Keine manuelle JSON-Bearbeitung ohne Backup!**
   Bevor du eine JSON-Datei in `data/database/` per Texteditor veränderst, erstelle eine Kopie.
2. **Daten aus Backup wiederherstellen:**
   Vor dem Import wurde ein Backup angelegt. Navigiere in das Verzeichnis:
   `C:\Users\Maik\Desktop\DosenHubV3\data\backups\migration\`
   Kopiere die entsprechende Backup-Datei (z. B. `users.json`, `points.json`) zurück in den Ordner `data/database/` (und überschreibe die fehlerhafte Datei).
3. **Server neu starten:**
   Starte den Dosenhub-Server neu, damit er die wiederhergestellten Dateien einliest.
## Phase 17.7 Schnellhilfe

- Doppelte Alerts:
  - `GET /api/livefeed?type=overlay.alert.requested&limit=20`
  - pruefen, ob Roh-Event und Folge-Event denselben `traceId` teilen
  - Legacy-OBS dedupliziert ab Phase 17.7 ueber `dedupeId/traceId`
- streamer.bot Warnung:
  - `GET /api/bridges/streamerbot/diagnostics`
  - wenn `mode=http-inbound` und `connectionState=waiting-for-events`, ist die Bridge bereit
  - nur ein wirklich fehlgeschlagener POST oder steigende `failedEvents` deuten auf ein echtes Bridge-Problem
- Goals falsch im OBS:
  - OBS-Quelle muss `/overlays/goals` verwenden
  - Admin nur ueber `/overlays/goals/admin`
## Phase 17.8 streamer.bot Chat kommt nicht an

- `GET /api/bridges/streamerbot/diagnostics`
- wenn `websocketClient.enabled=true`, aber `connectionState=error` oder `reconnecting`:
  - streamer.bot WebSocket Server auf `127.0.0.1:8080` pruefen
  - optional `POST /api/bridges/streamerbot/websocket/reconnect`
- wenn `connectionState=subscribed` oder `waiting-for-events`, aber keine Chatnachrichten ankommen:
  - streamer.bot Trigger/Plattformstatus pruefen
  - im Dashboard `receivedEvents` beobachten
  - Test im Twitch-Chat mit normaler Nachricht und mit `!dosen`
- wenn noetig, HTTP-Fallback weiter nutzen ueber `POST /api/bridges/streamerbot/events`

## Phase 17.9 streamer.bot WebSocket Subscribe & Handschlag-Probleme

- **Symptom**: streamer.bot WebSocket-Status zeigt `connected`, aber keine Events kommen an und `subscribedAt` ist null.
  - **Ursache**: Der Subscribe-Handshake schlug fehl oder wurde blockiert.
  - **Behebung**: Diagnostics unter `GET /api/bridges/streamerbot/diagnostics` prüfen. Prüfe `subscribeStatus` (muss `ok` sein) und `subscribeRequestId` (z.B. `dosenhub-subscribe-twitch`).
  - Du kannst einen erneuten Subscribe-Handshake manuell auslösen via `POST /api/bridges/streamerbot/websocket/subscribe` oder im Dashboard auf "WebSocket reconnect" klicken.
- **Symptom**: In den Diagnostics steigen die Zähler bei `ignoredRawMessages` oder `invalidJsonMessages`.
  - **Erklärung**: Das bedeutet, streamer.bot sendet leere Daten (z.B. Heartbeats) oder ungültiges JSON. Dies führt **nicht** mehr zu einem Verbindungsabbruch und wird im Hintergrund sicher verworfen.
  - **Fehleranalyse**: Die letzten 5 rohen Websocket-Datenpakete können über `GET /api/bridges/streamerbot/websocket/raw-debug` eingesehen werden.

## Phase 17.11 Handshake-Sequenz-Fehler oder Hello-Timeout
- **Symptom**: Preflight warnt über `waiting for Hello handshake` oder Diagnostics meldet `Hello handshake response timeout`.
  - **Erklärung**: Dosenhub hat sich per WebSocket verbunden, streamer.bot hat aber innerhalb von 5 Sekunden keine `Hello`-Begrüßung gesendet. Daher durfte Dosenhub sich nicht abonnieren (um Verwerfungen zu verhindern).
  - **Fehlersuche & Behebung**:
    1. Prüfe, ob der streamer.bot WebSocket-Server läuft und verbindungsbereit ist.
    2. Prüfe in der `receivedMessages`-Liste unter `/api/bridges/streamerbot/websocket/raw-debug`, ob Daten empfangen wurden.
    3. Führe einen Reconnect im Dashboard aus oder rufe `POST /api/bridges/streamerbot/websocket/reconnect` auf.
- **Symptom**: Diagnostics meldet `Authentication response timeout` oder `streamer.bot WebSocket Request fehlgeschlagen` (im Zusammenhang mit Authentifizierung).
  - **Erklärung**: streamer.bot verlangt ein Passwort, das in Dosenhub falsch konfiguriert ist, oder streamer.bot antwortet nicht auf die Authentifizierung.
  - **Behebung**:
    1. Passwort in `config/app.config.json` unter `streamerbot.inbound.websocket.authentication` prüfen.
    2. Falls streamer.bot keine Authentifizierung erfordert, diese in der Konfiguration deaktivieren.
- **Symptom**: Manueller `/subscribe` Aufruf schlägt fehl mit `WebSocket not initialized`.
  - **Erklärung**: Du hast versucht, manuell zu abonnieren, bevor die Verbindung mit streamer.bot den `Hello`-Handshake abgeschlossen hat.
  - **Behebung**: Warte, bis der Handshake abgeschlossen ist (Diagnostics zeigt `sessionId` an), und versuche es erneut.