🤖 Wie Robert funktioniert

Robert ist der WhatsApp-Bot von Blockbuster. Diese Seite erklärt im Detail, aus welchen Teilen das System besteht, wie Daten fließen und was wo verarbeitet wird.

1. Architektur: vier Container, ein Tunnel

Alle vier Container laufen per Docker Compose auf einem Raspberry Pi. Der Bot spricht mit dem Backend ausschließlich über das interne Docker-Netz und authentifiziert sich bei jedem Request mit einem gemeinsamen Geheimnis (X-Bot-Secret-Header). Von außen ist nur der Cloudflare-Tunnel erreichbar; der QR-Code zum Koppeln des WhatsApp-Kontos ist nur lokal auf dem Pi abrufbar.

2. Eingehende Nachrichten: Roberts Entscheidungs-Pipeline

Jede Nachricht in einer Gruppe oder per DM durchläuft dieselbe Kette von Prüfungen, bevor Robert antwortet:

• Befehle zuerst: Nachrichten mit ! werden direkt verarbeitet und gehen nie an die KI. !absagen und !plan sind Team-Admins vorbehalten (im Admin-Bereich unter „🛡️ Robert-Admins“ eingestellt). Im Privatchat zeigt !absagen eine nummerierte Liste aller anstehenden Termine (!absagen 2 sagt Nr. 2 ab), und !plan liefert den zuletzt generierten Trainingsplan.
• Pro Gruppe steuerbar: Im Admin-Bereich lässt sich je Gruppe einstellen, ob Robert frei antwortet, nur wenn er mit @ erwähnt wird, oder gar nicht. Die Erwähnung erkennt er sowohl über seine Telefonnummer-ID als auch über seine WhatsApp-Lid.
• Absagen per Sprache: Sagt ein Admin z. B. „Robert, sag das Training ab“, darf das Modell ein Absage-Werkzeug aufrufen. Der Bot prüft serverseitig noch einmal, dass die Person wirklich Admin ist — egal, was das Modell behauptet.
• Schutz vor Schleifen: Pro Chat gilt eine kurze Abklingzeit zwischen Antworten, und Nachrichten werden auf 1000 Zeichen gekürzt, bevor sie an die KI gehen.

3. Roberts Wissen: was er weiß und woher

Robert „weiß“ nichts von sich aus — vor jeder Antwort bekommt er einen frischen Kontextblock mit Daten aus drei Quellen:

Quelle	Inhalt	Aktualisierung
Backend	Gruppen & Trainingstage, anstehende Termine und Spiele (inkl. Zu-/Absagen), heutiges Datum	Der Bot holt die Konfiguration alle 15–30 Sekunden vom Backend
Open-Meteo	Wettervorhersage je Termin („🌧️ Schauer 8–23 °C, 30 % Regen“)	Backend cached 3 h pro Ort; nur für Termine in den nächsten 16 Tagen
mixedvolleyball.net	Tabellenplatz, Punkte, Bilanz, letztes Ergebnis und nächstes Spiel von Blockbuster	Backend cached 6 h (SportsPress-API der Liga)

Für alles, was darüber hinausgeht (aktuelle Fragen, Ergebnisse, Allgemeinwissen), darf Robert eine Websuche über OpenAIs eingebautes Such-Werkzeug starten. Damit eine gesprächige Gruppe keine Kosten produziert, ist die Suche auf eine Tagesobergrenze pro Chat gedeckelt (Standard: 25). Schlägt die Suche fehl, antwortet er ohne sie, statt zu schweigen.

4. Gedächtnis: kurzfristig, langfristig, persistent

• Kurzzeitgedächtnis: die letzten Wortmeldungen wörtlich, in Gruppen mit Absender-Namen („Lena: wann spielen wir?“). Nach 30 Minuten Ruhe wird es fallen gelassen.
• Langzeitgedächtnis: ein laufend verdichteter Merkzettel (max. 1500 Zeichen) pro Chat — Fakten wie Spitznamen, Positionen oder Running Gags überleben so beliebig lange.
• Neustart-fest: beim Start lädt Robert alle Gedächtnisse aus der Datenbank zurück; Chats, die länger als 30 Tage inaktiv waren, bleiben archiviert und belegen keinen Arbeitsspeicher.

5. Ausgehende Posts: die Outbox

Robert postet nie „von selbst“ — das Backend stellt Aufträge in Warteschlangen, die der Bot zyklisch abarbeitet und quittiert. Erst nach erfolgreicher Zustellung wird ein Auftrag als erledigt markiert; schlägt etwas fehl, bleibt er liegen und wird beim nächsten Durchlauf erneut versucht.

• Termin-Karten: Termine werden als native WhatsApp-Termine gepostet (mit Titel, Zeit, Ort, Beschreibung). Zu- und Absagen passieren direkt in WhatsApp („Teilnehmen / Vielleicht / Absagen“) — Robert liest sie etwa einmal pro Minute mit und spiegelt sie ins Backend, damit der Admin-Bereich sie anzeigt und Robert Fragen wie „Wer kommt morgen?“ beantworten kann.
• Liga-Ergebnisse: Taucht im Liga-Feed ein neues Endergebnis von Blockbuster auf, postet Robert Spielstand, Sätze und Tabellenplatz automatisch in die Spiel-Gruppen — pro Ergebnis genau einmal (in der Datenbank vermerkt) und nur, solange es jünger als eine Woche ist.
• Drosselung: Direktnachrichten (z. B. Abstimmungs-Links) gehen mit 4 Sekunden Abstand raus, damit WhatsApp den Account nicht als Spam einstuft.
• Absagen: Bei einer Absage editiert Robert die ursprüngliche Termin-Karte auf „abgesagt“ (ausgegraut) und postet zusätzlich eine Nachricht in die Gruppe.
• Mitglieder-Abgleich: Alle 2 Minuten meldet der Bot die Mitglieder seiner Gruppen (außer als „Archiv“ markierten) ans Backend, damit Telefonnummern den Spieler-Profilen zugeordnet werden können.

6. Trainingsplanung mit KI: vom Wunsch zum Plan

• 24 Stunden vor der Frist erinnert Robert die Gruppe einmalig an die Umfrage.
• Der Planer (ein stärkeres Modell als im Chat, konfigurierbar über OPENAI_PLAN_MODEL) bekommt Dauer, reservierte Spielzeit und die Wünsche sortiert nach Stimmen — und muss mit dem Material auskommen, das die Halle hergibt: Netz und Bälle.
• Statt einer Textwand postet Robert nur einen Link auf die Planseite. Der Admin kann den Plan danach jederzeit im Tool neu generieren oder mit Zusatz-Anweisungen (z. B. „erste Stunde nur 2 Übungen") anpassen — der Link in der Gruppe zeigt immer den aktuellen Stand.
• Ein Versuch pro Viertelstunde: schlägt die Generierung fehl, probiert es der Zeitplaner später erneut, statt Kosten zu produzieren.
• Wiederkehrende Trainings (Mo/Mi) postet der Zeitplaner automatisch ab 06:00 am Trainingstag — ganz ohne KI, aus den hinterlegten Trainingszeiten.

7. Spiele & Aufstellung: die Abstimmung

• Jede Stimme wird in einer Datenbank-Transaktion mit Zeilensperre gezählt — zwei gleichzeitige Stimmen können sich nicht gegenseitig überschreiben.
• Die Abstimmungs-Links enthalten ein zufälliges Token; zusätzlich schützt ein persönliches Passwort davor, dass jemand fremde Links aus dem Gruppenchat benutzt.
• Spieler sehen Namen, aber keine Telefonnummern anderer — die vollständigen Daten sieht nur der Admin.

8. Was an OpenAI geht — und was nicht

Geht an OpenAI	Bleibt im System
Der Nachrichtentext (max. 1000 Zeichen), Absender-Vorname in Gruppen, der Kontextblock (Termine, Trainingszeiten, Wetter, Liga), das Chat-Gedächtnis und — für Trainingspläne — die gesammelten Wünsche.	Telefonnummern, Abstimmungs-Tokens und Passwörter, Gruppen-IDs, API-Schlüssel, sowie sämtliche Datenbank-Inhalte, die nicht ausdrücklich Teil des Kontextblocks sind.

Es gibt zwei getrennte API-Schlüssel: einen für Roberts Chat-Antworten (OPENAI_API_KEY, Modell gpt-4o-mini) und optional einen eigenen für die Trainingsplan-Generierung (OPENAI_PLAN_API_KEY, Modell gpt-5). Alle Schlüssel und Passwörter liegen ausschließlich in GitHub-Secrets bzw. der .env auf dem Pi — nie im Code.

Alle Aufrufe laufen mit store: false — OpenAI speichert die Anfragen und Antworten nicht auf seiner Plattform (keine Logs im OpenAI-Dashboard). Die Unterhaltungen liegen ausschließlich in Roberts eigenem Gedächtnis (bot_memory), das jede Person per !delete löschen kann.

9. Betrieb: Deploy, Gesundheit, Wiederanlauf

• CI/CD: Jeder Push baut und testet Backend (JUnit + Testcontainers) und Bot (Lint + Tests) auf GitHub Actions; erst danach deployt ein Runner auf dem Pi die neuen Images. Schlägt der Health-Check fehl, werden automatisch die vorherigen Images wiederhergestellt.
• Healthchecks: Docker prüft Backend (/api/me) und Bot (/health) laufend; das Backend startet erst, wenn die Datenbank bereit ist.
• Heartbeat: Der Bot meldet alle 30 s seinen Verbindungsstatus ans Backend — die Web-App zeigt einen Banner, wenn Robert getrennt ist oder einen neuen QR-Scan braucht.
• Selbstheilung: Bei Verbindungsabriss verbindet sich der Bot mit wachsenden Wartezeiten neu; klappt das sechsmal nicht, beendet er sich und Docker startet den Container frisch. Die WhatsApp-Sitzung überlebt in einem Docker-Volume, ebenso die Datenbank.
• Schema-Migrationen: Flyway führt nummerierte SQL-Migrationen beim Start aus — die Datenbank passt damit immer zur laufenden Code-Version.

10. Deine Daten: was gespeichert wird – und wie du sie löschst

Robert speichert nur, was er zum Organisieren von Training und Spielen braucht. Alle Daten liegen in der PostgreSQL-Datenbank auf dem Raspberry Pi (siehe Abschnitt 1); von außen ist nur der Cloudflare-Tunnel erreichbar.

Daten	Wozu	Aufbewahrung
Telefonnummer & WhatsApp-Name der Mitglieder seiner Gruppen	Zuordnung zu Spielerprofilen, Schlüssel- und Abstimmungs-Funktionen	solange du mit Robert in einer Gruppe bist (laufend abgeglichen)
Gesprächsverlauf mit Robert (Gedächtnis pro Chat)	damit er sich im Chat an den Verlauf erinnert	Kurzzeit ~30 min, Merkzettel dauerhaft – per !delete löschbar
Spielerprofil (interner Name, Nummer, Positionen)	Aufstellung & Voting	bis ein Admin es löscht
Zu-/Absagen & abgegebene Stimmen	Teilnahme & Aufstellung	am Termin/Spiel; Stimmen werden nur anonym aggregiert gespeichert
Interessenten-Anfragen (Onboarding neuer Spieler:innen)	Vorab-Einschätzung, ob jemand ins Team passt	bis ein Admin annimmt/ablehnt – per !delete löschbar

An OpenAI gehen nur die in Abschnitt 8 genannten Inhalte; Telefonnummern, Tokens und Passwörter bleiben im System. Weitergehende Auskunfts- oder Löschwünsche richtest du an die im Impressum genannte Kontaktadresse.

Impressum