tippspiel/projektplan_wm2026_tippspiel.md

Projektplan: WM 2026 Tippspiel — Staffbase Custom Plugin

Projekt: WM 2026 Tippspiel Auftraggeber: GEALAN Fenster-Systeme GmbH Erstellt: April 2026 Version: 1.0 Status: Initialisierung

---

1. Projektziel & Vision

1.1 Zielsetzung

Entwicklung eines interaktiven Tippspiel-Plugins für die FIFA Weltmeisterschaft 2026 (USA/Kanada/Mexiko, 11. Juni – 19. Juli 2026), das nahtlos in die bestehende Staffbase-Mitarbeiter-App von GEALAN integriert wird. Alle Mitarbeitenden können über die gewohnte Staffbase-Oberfläche — auf Mobile und Desktop — ihre Tipps abgeben, Ergebnisse verfolgen und die Rangliste einsehen.

1.2 Kernziele

• Mitarbeiterbindung und -engagement rund um die WM 2026 stärken
• Niedrigschwellige Teilnahme: kein separates Login, keine externe App nötig
• Vollständige Integration in die bestehende Staffbase-Instanz von GEALAN
• Mehrsprachige Unterstützung (Deutsch, Englisch — erweiterbar)
• Skalierbar für zukünftige Turniere (EM, CL etc.)

1.3 Nicht-Ziele (Out of Scope v1.0)

• Echte Geldwetten oder externe Zahlungsabwicklung
• Integration mit externen sozialen Netzwerken
• Eigene mobile App (kein separates iOS/Android-App-Release)

---

2. Technische Architektur

2.1 Integrationsmodell: Staffbase Custom Plugin

Das Tippspiel wird als Staffbase Custom Plugin realisiert. Custom Plugins sind externe Web-Applikationen, die per iFrame in die Staffbase-Plattform eingebettet werden. Staffbase übernimmt die Authentifizierung der Mitarbeitenden automatisch über JWT-Tokens (RS256), sodass kein separates Benutzerkonto für das Tippspiel benötigt wird.

Vorteile dieses Ansatzes:

• Vollständige technische Freiheit bei Backend, Frontend und Datenbank
• Automatisches Single Sign-On via Staffbase JWT
• Funktioniert auf iOS-App, Android-App und Web-Browser
• Keine Änderungen an der Staffbase-Instanz selbst notwendig

2.2 Architektur-Übersicht

┌─────────────────────────────────────────────┐
│           Staffbase-Plattform (GEALAN)       │
│                                             │
│  ┌──────────────────────────────────────┐   │
│  │  Custom Plugin (iFrame)              │   │
│  │  → Tippspiel-Frontend (React)        │   │
│  └──────────────┬───────────────────────┘   │
│                 │ JWT Token (automatisch)    │
└─────────────────│───────────────────────────┘
                  │ HTTPS
         ┌────────▼─────────┐
         │  Backend API      │
         │  (Node.js/Express)│
         │  + JWT-Validierung│
         └────────┬──────────┘
                  │
         ┌────────▼──────────┐
         │  Datenbank        │
         │  (PostgreSQL)     │
         │  Supabase Managed │
         └───────────────────┘
                  │
         ┌────────▼──────────┐
         │  WM-Spielplan API │
         │  football-data.org│
         └───────────────────┘

2.3 Technologie-Stack

Schicht	Technologie	Begründung
Frontend	React + TypeScript	Moderner Standard, große Community, passt zu Staffbase Client SDK
Staffbase Integration	@staffbase/plugins-client-sdk	Offizielle Brücke zwischen iFrame und Staffbase-App
Backend	Node.js + Express	Passt nahtlos zum Staffbase Node.js SDK
Auth / SSO	@staffbase/staffbase-plugin-sdk	JWT-Validierung (RS256/PKCS8)
Datenbank	PostgreSQL via Supabase	Managed, DSGVO-konform (EU-Region wählbar), einfaches Setup
Hosting	Railway oder Render	HTTPS out-of-the-box, einfaches Deployment, kostengünstig
WM-Spielplan	football-data.org API	Kostenfreie WM-Daten inkl. Ergebnisse, Teams, Gruppen
Caching	Redis (optional)	Spielplandaten cachen, Rate-Limit-Entlastung
CI/CD	GitHub Actions	Automatisiertes Deployment

2.4 Staffbase SDK — Verfügbare Nutzerdaten via JWT

Bei jedem Aufruf des Plugins stellt Staffbase automatisch folgende Nutzerdaten bereit:

Feld	Beschreibung	Verwendung im Tippspiel
userId	Eindeutige Staffbase-User-ID	Primärschlüssel für Tipps & Rangliste
fullName	Vollständiger Name	Anzeigename in der Rangliste
locale	Spracheinstellung (z.B. de_DE)	Automatische Sprachumschaltung
role	Staffbase-Rolle (admin, reader…)	Admin-Bereich nur für Admins sichtbar
branchId	Instanz-/Bereichs-ID	Für standortbezogene Auswertungen

---

3. Funktionsumfang (Features)

3.1 Kernfunktionen (MVP — Pflicht für v1.0)

F1 — Benutzer & Authentifizierung

• Automatischer Login via Staffbase SSO (JWT) — kein separates Konto
• Benutzerprofil mit Name und Gesamtpunkten
• Rollenbasierter Zugriff: Normaler Nutzer vs. Admin

F2 — WM-Spielplan

• Anzeige aller 104 WM-Spiele (Gruppenphase + KO-Runde)
• Automatische Synchronisation mit football-data.org API
• Anzeige von Datum, Uhrzeit (lokalisiert), Stadion, Teams, aktueller Ergebnisstatus

F3 — Tipp-Eingabe

• Tipp abgeben: Ergebnis (Heimtore : Auswärtstore) pro Spiel
• Tipp nur möglich bis Anpfiff (Deadline-Schutz)
• Tipp-Änderung bis zur Deadline erlaubt
• Visuelle Bestätigung bei gespeichertem Tipp

F4 — Punkte-System

• Ergebnis exakt richtig: 3 Punkte
• Tendenz richtig (Sieg/Remis/Niederlage): 1 Punkt
• Falsch: 0 Punkte
• Bonus-Punkte für KO-Runde konfigurierbar (z.B. ×2 ab Halbfinale)
• Automatische Berechnung nach Ergebnis-Eintrag durch Admin

F5 — Rangliste

• Live-Gesamtrangliste aller Teilnehmenden
• Anzeige: Platz, Name, Punkte, Tipp-Quote
• Filterbar nach Abteilung oder Standort (via Staffbase-Gruppen)
• Eigene Position stets sichtbar (auch wenn außerhalb der Top 10)

F6 — Admin-Bereich

• Spielergebnisse manuell eintragen / korrigieren
• Punkte automatisch neu berechnen nach Eintrag
• Übersicht aller Tipps pro Spiel
• Teilnahme-Statistiken (Anzahl Tipps, aktive Nutzer)

3.2 Erweiterungen (Nice-to-have — v1.1 oder später)

Feature	Beschreibung	Aufwand
Push-Benachrichtigungen	Ergebnisse-Update via Staffbase News API	Mittel
Gruppenphase-Tipper	Tipp auf Gruppensieger/-zweiten	Mittel
Turniersieger-Tipp	Einmaliger Tipp auf WM-Sieger (×5 Punkte)	Klein
Mini-Ligen	Interne Teams (z.B. nach Abteilung)	Groß
Kommentar-Funktion	Tipps kommentieren	Klein
Tipp-Analyse	Auswertung: beliebteste Tipps, Überraschungen	Mittel
Automatische Ergebnis-Synchronisation	Polling football-data.org, kein manuelles Eintragen	Mittel

---

4. Datenbankschema

4.1 Kerntabellen

-- Nutzer (befüllt automatisch via JWT bei erstem Login)
CREATE TABLE users (
  id           VARCHAR(64) PRIMARY KEY,  -- Staffbase userId
  full_name    VARCHAR(255) NOT NULL,
  locale       VARCHAR(10) DEFAULT 'de_DE',
  role         VARCHAR(20) DEFAULT 'reader',
  branch_id    VARCHAR(64),
  created_at   TIMESTAMPTZ DEFAULT NOW(),
  last_seen_at TIMESTAMPTZ DEFAULT NOW()
);

-- WM-Spiele (synchronisiert via football-data.org)
CREATE TABLE matches (
  id            SERIAL PRIMARY KEY,
  external_id   VARCHAR(32) UNIQUE NOT NULL,  -- ID aus football-data.org
  stage         VARCHAR(50) NOT NULL,          -- 'GROUP_STAGE', 'ROUND_OF_16', ...
  group_name    VARCHAR(10),                   -- 'A', 'B', ... (NULL in KO-Runde)
  home_team     VARCHAR(100) NOT NULL,
  away_team     VARCHAR(100) NOT NULL,
  kickoff_at    TIMESTAMPTZ NOT NULL,
  home_score    SMALLINT,                      -- NULL bis Abpfiff
  away_score    SMALLINT,
  status        VARCHAR(20) DEFAULT 'SCHEDULED' -- SCHEDULED, IN_PLAY, FINISHED
);

-- Tipps
CREATE TABLE predictions (
  id              SERIAL PRIMARY KEY,
  user_id         VARCHAR(64) REFERENCES users(id),
  match_id        INTEGER REFERENCES matches(id),
  predicted_home  SMALLINT NOT NULL,
  predicted_away  SMALLINT NOT NULL,
  points_earned   SMALLINT,                    -- NULL bis Spiel ausgewertet
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE (user_id, match_id)
);

-- Rangliste (materialized view oder separate Tabelle für Performance)
CREATE MATERIALIZED VIEW leaderboard AS
  SELECT
    u.id AS user_id,
    u.full_name,
    u.branch_id,
    COALESCE(SUM(p.points_earned), 0) AS total_points,
    COUNT(p.id) AS total_predictions,
    COUNT(CASE WHEN p.points_earned = 3 THEN 1 END) AS exact_hits,
    RANK() OVER (ORDER BY COALESCE(SUM(p.points_earned), 0) DESC) AS rank
  FROM users u
  LEFT JOIN predictions p ON p.user_id = u.id
  GROUP BY u.id, u.full_name, u.branch_id;

---

5. API-Design (Backend)

5.1 Endpunkte

Method	Endpunkt	Beschreibung	Auth
GET	/api/matches	Alle Spiele mit Status	JWT
GET	/api/matches/:id	Einzelnes Spiel	JWT
GET	/api/predictions/me	Eigene Tipps	JWT
POST	/api/predictions	Tipp abgeben	JWT
PUT	/api/predictions/:id	Tipp ändern (vor Deadline)	JWT
GET	/api/leaderboard	Gesamtrangliste	JWT
GET	/api/leaderboard/me	Eigene Position	JWT
PUT	/api/admin/matches/:id/result	Ergebnis eintragen	JWT + Admin
POST	/api/admin/recalculate	Punkte neu berechnen	JWT + Admin
GET	/api/admin/stats	Teilnahmestatistiken	JWT + Admin

5.2 Authentifizierung

Jeder Request vom Frontend sendet den Staffbase JWT im Header:

Authorization: Bearer <staffbase-jwt-token>

Das Backend validiert den Token mit dem @staffbase/staffbase-plugin-sdk (RS256, Public Key aus Staffbase Studio). Bei gültigem Token werden Nutzer-ID, Name, Rolle und Locale aus dem Token extrahiert und der Nutzer automatisch in der users-Tabelle angelegt (upsert).

---

6. Projektphasen & Zeitplan

Gesamtlaufzeit: 10 Wochen (April — Mitte Juni 2026)

Phase 1 — Setup & Fundament (Woche 1–2)

Aufgabe	Verantwortlich	Aufwand
Staffbase Plugin registrieren (Plugin-ID + Public Key)	Admin	0,5 Tage
Node.js Projekt-Skeleton generieren (create-staffbase-plugin-nodejs)	Entwicklung	0,5 Tage
Git-Repository anlegen, CI/CD konfigurieren (GitHub Actions)	Entwicklung	1 Tag
Hosting-Umgebung aufsetzen (Railway/Render)	Entwicklung	0,5 Tage
Supabase-Projekt anlegen, Datenbankschema deployen	Entwicklung	1 Tag
JWT-Authentifizierung implementieren und testen	Entwicklung	1 Tag
football-data.org API-Key beantragen und testen	Entwicklung	0,5 Tage

Meilenstein: Authentifizierter API-Call von Staffbase-Plugin zu Backend funktioniert.

Phase 2 — Kern-Backend (Woche 3–4)

Aufgabe	Verantwortlich	Aufwand
Spielplan-Synchronisation (football-data.org → DB)	Entwicklung	2 Tage
REST API vollständig implementieren	Entwicklung	3 Tage
Tipp-Logik mit Deadline-Prüfung	Entwicklung	1 Tag
Punkte-Berechnungslogik	Entwicklung	1 Tag
Ranglisten-Abfrage (inkl. Materialized View)	Entwicklung	1 Tag
Unit-Tests für Kernlogik	Entwicklung	1 Tag

Meilenstein: Vollständige Backend-API testbar via Postman/API-Client.

Phase 3 — Frontend (Woche 5–7)

Aufgabe	Verantwortlich	Aufwand
React-Projekt aufsetzen, Staffbase Client SDK integrieren	Entwicklung	1 Tag
Spielplan-Übersicht (nach Datum / Gruppe filtern)	Entwicklung	2 Tage
Tipp-Eingabeformular mit Validierung	Entwicklung	2 Tage
Rangliste mit Pagination	Entwicklung	1,5 Tage
Admin-Bereich (Ergebnis eintragen, Statistiken)	Entwicklung	2 Tage
Responsive Design (Mobile-first für Staffbase App)	Entwicklung	1,5 Tage
Mehrsprachigkeit DE/EN	Entwicklung	1 Tag

Meilenstein: Vollständige App funktionsfähig im Browser (ohne Staffbase-Integration).

Phase 4 — Staffbase-Integration & Test (Woche 8–9)

Aufgabe	Verantwortlich	Aufwand
Plugin-URL in Staffbase Studio hinterlegen	Admin	0,5 Tage
iFrame-Test in Staffbase Web und Mobile App	Entwicklung	1 Tag
End-to-End-Tests mit echten Staffbase-Nutzern	Entwicklung + QA	2 Tage
Bugfixing aus Testphase	Entwicklung	2 Tage
Performance-Test (Last: viele gleichzeitige Tipps)	Entwicklung	1 Tag
DSGVO-Check: keine unautorisierten Daten gespeichert	PM/Legal	1 Tag

Meilenstein: Plugin läuft stabil in der Staffbase-Staging-Umgebung.

Phase 5 — Launch & Betrieb (Woche 10 + laufend)

Aufgabe	Verantwortlich	Aufwand
Go-Live in Staffbase Produktivumgebung	Admin + Entwicklung	1 Tag
Kommunikation an Mitarbeitende (via Staffbase News Channel)	Kommunikation	0,5 Tage
Monitoring & Alerting einrichten (Uptime, Fehler-Logs)	Entwicklung	1 Tag
WM-Start-Phase begleiten (Hotfixes, Support)	Entwicklung	laufend
Tägliche Ergebnispflege (manuell oder automatisch)	Admin	laufend

---

7. Ressourcen & Rollen

Rolle	Verantwortlichkeiten	Zeitaufwand
Projektleiter/PM	Steuerung, Stakeholder-Kommunikation, Abnahme	~20% (verteilt)
Fullstack-Entwickler (1–2)	Backend, Frontend, Deployment, Tests	100% über 8 Wochen
Staffbase-Admin	Plugin-Registrierung, Studio-Konfiguration, Rollout	~5%
Kommunikation	Launch-Kommunikation, Mitarbeitende informieren	~5%
QA (optional)	Testen, Bugmeldungen	~20% in Phase 4

---

8. Infrastruktur & Kosten

8.1 Hosting (monatlich, geschätzt)

Dienst	Zweck	Kosten/Monat
Railway / Render	Backend-Hosting (Node.js)	~5–15 €
Supabase	PostgreSQL (Free Tier reicht für ~500 User)	0 € (Free) / 25 € (Pro)
football-data.org	WM-Spielplan API	0 € (Free Tier)
GitHub	Code-Repository + CI/CD	0 € (Free)
Gesamt		~5–40 € / Monat

8.2 Einmalige Kosten (Entwicklung)

Gemäß separater Aufwandsschätzung (siehe Projektphasen). Bei internem Entwicklerteam: reine Zeitkosten. Bei externer Vergabe: ca. 15.000–25.000 € (je nach Erfahrungsniveau und Scope).

---

9. Risiken & Maßnahmen

Risiko	Wahrscheinlichkeit	Auswirkung	Maßnahme
Staffbase JWT-Integration schlägt fehl	Niedrig	Hoch	Frühzeitig in Phase 1 testen, Staffbase Support einbinden
football-data.org API unzuverlässig	Mittel	Mittel	Spielplandaten lokal cachen, manuelle Eingabe als Fallback
Zu viele gleichzeitige Nutzer (WM-Start)	Mittel	Mittel	Load-Test vor Go-Live, Auto-Scaling auf Hosting-Plattform
DSGVO: unbeabsichtigte Datenspeicherung	Niedrig	Hoch	Nur JWT-Daten speichern, kein Tracking, Datenschutzprüfung
Entwicklungsrückstand (Urlaube, Krankheit)	Mittel	Mittel	Puffer von 1 Woche eingeplant, MVP-Scope reduzierbar
WM-Spielplan ändert sich (Absagen, Verlegungen)	Niedrig	Niedrig	Automatische API-Synchronisation

---

10. Definition of Done (DoD)

Ein Feature gilt als fertig, wenn:

1. Funktionalität implementiert und manuell getestet
2. Unit-Tests vorhanden (Backend-Logik)
3. Responsive auf Mobile und Desktop
4. In Staffbase-iFrame getestet (Web + App)
5. Kein Fehler in den Browser-Konsolen-Logs
6. Code reviewed und in main-Branch gemergt

Das Gesamtprojekt gilt als abgenommen, wenn:

1. Alle MVP-Features (F1–F6) funktionsfähig sind
2. Mind. 20 Test-Nutzer einen Tipp abgegeben haben (Pilottest)
3. Performance-Test bestanden (< 2 Sekunden Ladezeit)
4. DSGVO-Prüfung abgeschlossen und dokumentiert
5. Go-Live in Produktivumgebung erfolgt

---

11. Nächste Schritte (Sofortmaßnahmen)

1. Plugin bei Staffbase registrieren → Staffbase Studio → Einstellungen → Plugins → neues Plugin anlegen → Plugin-ID und Public Key notieren
2. Entwicklungsumgebung aufsetzen → npx create-staffbase-plugin-nodejs@latest wm2026-tippspiel
3. football-data.org API-Key beantragen → https://www.football-data.org/client/register
4. Supabase-Projekt anlegen → https://supabase.com (EU-Region Frankfurt)
5. Kickoff-Meeting mit allen Beteiligten (PM, Entwicklung, Staffbase-Admin, Kommunikation)

---

Anhang A: Nützliche Links & Ressourcen

Ressource	URL
Staffbase Developer Portal	https://developers.staffbase.com
Staffbase Custom Plugin Übersicht	https://developers.staffbase.com/concepts/customplugin-overview/
Staffbase Plugins Client SDK	https://github.com/Staffbase/plugins-client-sdk
Staffbase Node.js SDK	https://github.com/Staffbase/plugins-sdk-nodejs
Staffbase Plugin Skeleton Generator	https://github.com/Staffbase/create-staffbase-plugin-nodejs
football-data.org API	https://www.football-data.org
Supabase	https://supabase.com
Railway Hosting	https://railway.app
Render Hosting	https://render.com
WM 2026 Spielplan (FIFA)	https://www.fifa.com/worldcup