docs: add Starface Modulcreator guide and webhook test script

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/starface-modul-anleitung.md

@@ -0,0 +1,130 @@
+# Starface Modulcreator – Busylight Integration
+
+## Übersicht
+
+Dieses Modul sendet bei jedem Anruf-Event einen HTTP-Request an den Busylight-Server,
+damit die Türschilder automatisch den Telefonstatus anzeigen.
+
+## Voraussetzungen
+
+- Starface Telefonanlage mit Modulcreator-Lizenz
+- Busylight-Server erreichbar unter `http://BUSYLIGHT-IP:8081`
+- Durchwahlen der Mitarbeiter im Busylight-Portal eingetragen
+
+## Modul im Modulcreator erstellen
+
+### Schritt 1: Neues Modul anlegen
+
+1. Starface Admin-Oberfläche öffnen
+2. **Admin** → **Modulcreator** (oder **Module** → **Modulcreator**)
+3. **Neues Modul erstellen**
+4. Modulinformationen:
+   - **Name**: `Busylight`
+   - **Beschreibung**: `Sendet Telefonstatus an Busylight Türschilder`
+   - **Vendor**: `cynfo GmbH`
+   - **Version**: `1.0.0`
+
+### Schritt 2: Modulkonfiguration (Instanz-Variablen)
+
+Unter **Modulkonfiguration** folgende Variablen anlegen:
+
+| Variable | Typ | Standardwert | Beschreibung |
+|----------|-----|-------------|-------------|
+| `busylight_url` | String | `http://100.95.224.14:8081` | URL des Busylight Webhook-Servers |
+
+### Schritt 3: Trigger konfigurieren
+
+1. **Trigger hinzufügen**: `Anruf-Trigger` (Call Trigger)
+2. **Trigger-Typ**: `Bei jedem Anruf` oder `Call State Changed`
+3. **Richtung**: Eingehend + Ausgehend (beide)
+
+### Schritt 4: Funktionsablauf erstellen
+
+Der Ablauf hat zwei Zweige:
+
+#### Zweig A: Anruf beginnt (callstart)
+
+1. **Bedingung**: Anrufstatus = `CONNECTED` (Anruf angenommen)
+2. **Aktion**: HTTP Request
+   - **Methode**: GET
+   - **URL**: `{busylight_url}/{called_number}/callstart`
+   - `{called_number}` = Die Durchwahl des angerufenen Benutzers
+
+#### Zweig B: Anruf endet (callend)
+
+1. **Bedingung**: Anrufstatus = `HANGUP` (Anruf beendet)
+2. **Aktion**: HTTP Request
+   - **Methode**: GET
+   - **URL**: `{busylight_url}/{called_number}/callend`
+
+### Schritt 5: Variablen-Mapping
+
+Die Starface-Variablen müssen auf die URL gemappt werden:
+
+| Starface-Variable | Beschreibung | Verwendung |
+|-------------------|-------------|-----------|
+| `${call.calledNumber}` | Durchwahl des Angerufenen | In URL als Durchwahl |
+| `${call.callingNumber}` | Nummer des Anrufers | Optional für Logging |
+| `${call.state}` | Aktueller Anrufstatus | Für Bedingung |
+
+**Hinweis:** Die genauen Variablennamen können je nach Starface-Version variieren.
+Im Modulcreator werden die verfügbaren Variablen als Dropdown angeboten.
+
+### Schritt 6: Modul speichern und aktivieren
+
+1. **Speichern** klicken
+2. **Modul exportieren** als `.sfm` Datei (für Backup)
+3. Unter **Module** → **Modulinstanzen** eine neue Instanz anlegen
+4. `busylight_url` auf die IP des Busylight-Servers setzen: `http://100.95.224.14:8081`
+5. **Aktivieren**
+
+## Testen
+
+### Von der Kommandozeile testen
+
+```bash
+# Anruf simulieren (Durchwahl 222 = Nicklas Janzen)
+curl http://100.95.224.14:8081/222/callstart
+# → Türschild sollte rot werden
+
+# Anruf beenden
+curl http://100.95.224.14:8081/222/callend
+# → Türschild sollte auf Zeiterfassungs-Status zurückspringen
+```
+
+### Im Busylight-Portal prüfen
+
+- **Dashboard**: Telefon-Badge sollte "Telefoniert" anzeigen
+- **Protokoll**: Einträge mit `phone_active` und `phone_end` sollten erscheinen
+
+## Alternative: Starface Rufnummernaktionen
+
+Falls kein Modulcreator verfügbar ist, können auch **Rufnummernaktionen** verwendet werden:
+
+1. **Admin** → **Rufnummern** → Durchwahl auswählen
+2. **Aktionen** → **Neue Aktion**
+3. **Bei Anrufbeginn**: HTTP Request an `http://BUSYLIGHT:8081/{durchwahl}/callstart`
+4. **Bei Anrufende**: HTTP Request an `http://BUSYLIGHT:8081/{durchwahl}/callend`
+
+**Nachteil:** Muss pro Durchwahl einzeln eingerichtet werden.
+
+## Fehlerbehebung
+
+### Türschild reagiert nicht
+
+1. Busylight-Server erreichbar? `curl http://100.95.224.14:8081/`
+2. Durchwahl im Busylight-Portal beim Benutzer eingetragen?
+3. Benutzer laut Zeiterfassung "anwesend" oder "homeoffice"?
+4. Starface-Modul aktiviert?
+5. Firewall: Port 8081 von der Starface zum Busylight-Server offen?
+
+### Falscher Benutzer wird rot
+
+- Prüfen ob die Durchwahl im Busylight-Portal dem richtigen Benutzer zugeordnet ist
+- Variable im Modulcreator: `${call.calledNumber}` (nicht `${call.callingNumber}`)
+
+### Türschild bleibt nach Anrufende rot
+
+- Prüfen ob das HANGUP-Event im Modul konfiguriert ist
+- Im Busylight-Protokoll prüfen ob `callend` ankommt
+- Manuell zurücksetzen: `curl http://100.95.224.14:8081/{durchwahl}/callend`

docs/test-starface.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Test-Script für Starface Busylight Webhook-Integration
+# Simuliert Anruf-Events für alle konfigurierten Durchwahlen
+
+BUSYLIGHT="http://100.95.224.14:8081"
+
+echo "=== Busylight Starface Webhook Test ==="
+echo ""
+
+# API Info prüfen
+echo "1. Busylight API erreichbar?"
+curl -s "$BUSYLIGHT/" | head -3
+echo ""
+
+# Durchwahl zum Testen (anpassen!)
+DW="${1:-222}"
+echo "2. Test mit Durchwahl: $DW"
+echo ""
+
+echo "   → Sende callstart..."
+RESULT=$(curl -s "$BUSYLIGHT/$DW/callstart")
+echo "   ← $RESULT"
+echo ""
+
+echo "   Warte 5 Sekunden (Türschild sollte jetzt ROT sein)..."
+sleep 5
+
+echo "   → Sende callend..."
+RESULT=$(curl -s "$BUSYLIGHT/$DW/callend")
+echo "   ← $RESULT"
+echo ""
+
+echo "3. Fertig! Türschild sollte jetzt zurück auf Zeiterfassungs-Status sein."
+echo ""
+echo "Verwendung: $0 [durchwahl]"
+echo "Beispiel:   $0 210    (Test mit Durchwahl 210)"