# Operations Runbook - Dosenhub V3

Stand: 2026-06-21

## 1. Start

1. In das Projekt wechseln: `C:\Users\Maik\Desktop\DosenHubV3`
2. Dosenhub starten:
   - bevorzugt: `start-dosenhub.bat`
   - alternativ: `npm run dev`
3. Dashboard im Browser oeffnen: [http://127.0.0.1:3000/](http://127.0.0.1:3000/)

## 2. Preflight

Vor jedem Stream:

```bash
npm run stream:preflight
```

Der Check prueft:

- Server online
- Modulzustand
- streamer.bot Bridge
- Bot Outbox
- Migration-Backups
- LAN-Konfiguration

Die LAN-Konfiguration ist korrekt, wenn `lanBaseUrl` auf `http://192.168.0.90:3000` steht.

## 3. URLs / OBS

Alle relevanten Links:

```bash
npm run stream:urls
```

Wichtige Overlay-Pfade:

- `/overlays/start`
- `/overlays/brb`
- `/overlays/alerts`
- `/overlays/chat`
- `/overlays/goals`
- `/overlays/end`
- `/overlays/wheel`

Bei Zwei-PC-Setups oder Tablet-/Handy-Vorschau die LAN-Links mit `192.168.0.90:3000` verwenden.

## 4. Legacy-Overlay-Status

Aktueller Stand:

- `start`, `brb`, `end`, `goals`: legacy-integrated
- `alerts`, `chat`, `wheel`: legacy-integrated
- `quests`, `pets`: placeholder

Wichtig:

- alte Inhalte und Assets bleiben erlaubt
- alte Technik bleibt aus
- keine lokale Soundausgabe in Dosenhub

## 5. streamer.bot

Dosenhub spielt keine Sounds selbst ab. Die Audioausgabe bleibt bei streamer.bot auf dem Gaming-PC.

Pruefen:

1. streamer.bot gestartet
2. Bridge-Widget im Dashboard
3. Testevent oder Demo-Event durchlaufen lassen

## 6. Backups und Logs

Backup-Check:

```bash
npm run stream:backup-check
```

Wichtige Pfade:

- `data/database/`
- `data/logs/`
- `data/backups/migration/`

## 7. Wenn etwas schieflaeuft

1. Dashboard und Livefeed pruefen
2. `npm run stream:preflight`
3. `npm run stream:urls`
4. `/api/overlays/legacy/status` pruefen
5. bei Overlay-Themen in `docs/LEGACY_OVERLAY_INTEGRATION.md` nachsehen
## Phase 17.7 Betriebshinweise

- Goals in OBS immer ueber `/overlays/goals` einbinden. Diese Route erzwingt jetzt den Legacy-OBS-Modus.
- Die Admin-/Bearbeitungsansicht fuer Goals liegt getrennt unter `/overlays/goals/admin`.
- streamer.bot-Checks:
  - Inbound-Bereitschaft pruefen ueber `GET /api/bridges/streamerbot/diagnostics`
  - Erwarteter Eingang: `POST /api/bridges/streamerbot/events`
  - "Wartet auf Events" ist fuer HTTP-Inbound normal und kein Ausfall.
- Bei doppelten Alerts zuerst `traceId` im Livefeed/Diagnostics pruefen. Identische Traces werden ab Phase 17.7 nur noch einmal an Legacy-OBS weitergereicht.
## Phase 17.8 streamer.bot Betrieb

- Empfohlene Zielkonfiguration fuer Maik:
  - streamer.bot WebSocket Server aktiv auf `ws://127.0.0.1:8080/`
  - Dosenhub WebSocket-Client aktiviert
  - HTTP `POST /api/bridges/streamerbot/events` als Fallback bestehen lassen
- So pruefst du den Eingang:
  - Dashboard oder `/streamerbot` oeffnen
  - `GET /api/bridges/streamerbot/diagnostics` pruefen
  - `websocketClient.receivedEvents` beobachten
  - eine Chatnachricht schreiben
  - bei Commands testen, ob `!dosen` im Command-System landet
- Deduplizierung:
  - gemeinsamer TTL-Cache fuer HTTP und WebSocket
  - bevorzugt ueber `eventId`, `messageId`, `traceId`
  - Fallback ueber `type + user + message + timestamp bucket`

## Phase 17.9 streamer.bot WebSocket Subscribe & Diagnostics
- **Subscription Handshake**: Der WebSocket-Client verbindet sich nicht nur, sondern abonniert Twitch-Events aktiv über einen `Subscribe`-Request.
  - Wenn `connectionState === 'connected'` aber `subscribedAt === null`, wird gewarnt: `"Verbunden, aber noch nicht subscribed."`
  - Ein erfolgreiches Abonnement wechselt in den Zustand `subscribed` bzw. `waiting-for-events`.
- **Diagnostics**:
  - `GET /api/bridges/streamerbot/diagnostics` zeigt die exakten Protokolldaten (`subscribeRequestId`, `subscribeStatus`, etc.) sowie Zähler für fehlerhafte Nachrichten (`ignoredRawMessages`, `invalidJsonMessages`).
  - `GET /api/bridges/streamerbot/websocket/raw-debug` zeigt die letzten 5 empfangenen Nachrichtenausschnitte (max. 200 Zeichen) zur Analyse leerer/fehlerhafter Frames.
- **Preflight**:
  - `npm run stream:preflight` liefert klare Hinweise, falls der Client verbunden, aber das Abonnement nicht aktiv ist.

## Phase 17.10 streamer.bot WebSocket Subscribe on Open
- **Sofortiges Senden**: Der Subscribe-Request wird direkt beim `open` Event an streamer.bot übertragen und wartet nicht auf Hello-Nachrichten.
- **Fehlersuche via Raw-Debug**:
  - `GET /api/bridges/streamerbot/websocket/raw-debug` gibt zwei Listen aus: `sentMessages` (enthält gesendete Subscribe-Requests mit Zeitstempel) und `receivedMessages` (enthält die empfangenen Frames).
  - So kannst du überprüfen, ob Dosenhub den Subscribe-Request abgesendet hat.
- **Preflight**:
  - `npm run stream:preflight` meldet detailliert:
    - `subscribe request was not sent` (wenn die Übermittlung fehlschlug)
    - `subscribe pending` (wenn gesendet, aber streamer.bot noch nicht geantwortet hat)
    - `subscribed` (wenn alles betriebsbereit ist)

## Phase 17.11 streamer.bot WebSocket Handshake Sequence Fix
- **Hello-First Handshake**: Dosenhub wartet nun nach dem Verbindungsaufbau (`open`) zwingend auf das `Hello`-Event von streamer.bot, bevor das Abonnement (`Subscribe`) gesendet wird.
- **Preflight & Diagnose**:
  - `npm run stream:preflight` zeigt im Übergangszustand vor dem Handshake: `WebSocket: connected, waiting for Hello handshake.`
  - Falls streamer.bot nach 5 Sekunden nicht auf die Verbindung mit `Hello` antwortet, wird `Hello handshake response timeout` als Fehler in den Diagnostics angezeigt.
- **Authentifizierung**: Ist in Dosenhub ein Passwort konfiguriert und fordert streamer.bot im `Hello`-Frame eine Authentifizierung an, wird erst `Authenticate` gesendet. Nach erfolgreicher Rückmeldung erfolgt automatisch die Subscription. Tritt bei der Authentifizierung nach 5 Sekunden keine Antwort ein, wird `Authentication response timeout` ausgegeben.
- **Manuelle Steuerung**: Der Endpoint `/subscribe` lehnt Aufrufe mit `WebSocket not initialized` ab, solange der Handshake noch nicht durch das `Hello`-Event abgeschlossen wurde.