Quiz26-53

Quiz-Plattform für den Studienkurs: Quiz erstellen und live zusammen spielen – ein Host zeigt Fragen, QR-Code und PIN auf dem großen Bildschirm, alle anderen spielen am Handy mit.

• Mitspielen geht immer, auch ohne Konto als Gast (nur mit Namen).
• Ein Konto braucht man, um Quiz zu speichern und zu hosten. Wer eingeloggt mitspielt, bekommt seine Punkte gespeichert.

Architektur

Browser ──HTTP──▶ Vercel (statische Seiten + Express-API als Serverless-Funktion)
   ▲                           │
   │                           ▼
   └──Realtime-Signal── Supabase (Postgres + Realtime)

• Vercel liefert public/ aus und betreibt die API (api/index.js → src/app.js).
• Supabase Postgres speichert Konten, Quiz, laufende Spiele und Ergebnisse (Schema quiz, nicht über die Supabase-REST-API erreichbar; die API verbindet sich mit der eigenen Rolle quiz_app).
• Supabase Realtime: Nach jeder Änderung an einem Spiel schickt die Datenbank ein update-Signal in den Kanal game:<PIN>. Host und Spieler laden daraufhin ihren Stand über die API neu. Ohne Realtime fragen die Seiten alle 2 Sekunden nach (Polling).
• Timer: Es gibt keinen dauerhaft laufenden Server. Eine Frage wird beim nächsten Abruf aufgelöst, sobald die Zeit abgelaufen ist oder alle geantwortet haben; die Browser fragen dafür zum Ablauf der Zeit automatisch nach.

Lokal entwickeln

Voraussetzung: Node.js 22+ und eine Postgres-Datenbank.

npm install
psql "$ADMIN_DB_URL" -f supabase/migrations/001_init.sql -f supabase/migrations/002_app_role.sql
psql "$ADMIN_DB_URL" -c "ALTER ROLE quiz_app PASSWORD 'local'"
cp .env.example .env   # DATABASE_URL eintragen
npm run dev            # http://localhost:3000

Ohne SUPABASE_URL/SUPABASE_PUBLISHABLE_KEY läuft alles per Polling.

Deployment (Vercel + Supabase)

1. Migrationen aus supabase/migrations/ im Supabase-Projekt ausführen und ein Passwort für quiz_app setzen.
2. Vercel-Projekt mit diesem GitHub-Repo verbinden (Framework: „Other“, kein Build nötig).
3. Umgebungsvariablen in Vercel setzen:
   • DATABASE_URL – Pooler-Verbindung (Transaction Mode, Port 6543) mit Benutzer quiz_app.<projekt-ref>
   • SUPABASE_URL – z. B. https://<projekt-ref>.supabase.co
   • SUPABASE_PUBLISHABLE_KEY – Publishable Key des Projekts (öffentlich, nicht geheim)
4. Jeder Push auf master wird automatisch deployt. /api/health prüft die Datenbankverbindung.

Ablauf

1. Konto erstellen bzw. anmelden (/) – nur zum Erstellen/Hosten und Punktesammeln nötig
2. Navigation: Nach dem Login führt eine schwebende Leiste am unteren Bildschirmrand zu Home (/dashboard: PIN eingeben, Kennzahlen, zuletzt gespielt), Quiz (/quizzes: eigene Quiz verwalten und starten), Bestenliste (/leaderboard) und Profil (/profile: Statistik, Erfolge, Ergebnisse, Abmelden). Sie steht nicht im Editor und nicht im Spiel selbst (Host-Bildschirm, Handy-Ansicht).
3. Editor (/edit): Titel, Fach, Fragen mit 2–4 Antworten, richtige Antwort, Zeitlimit
4. Starten → Host-Bildschirm (/host?pin=…) mit QR-Code, PIN und Teilnehmerliste
5. Teilnehmende scannen den QR-Code oder geben die PIN ein (/play) – als Gast mit Namen oder eingeloggt mit ihrem Nutzernamen
6. Host steuert: Quiz starten → Auflösen (automatisch nach Ablauf der Zeit oder wenn alle geantwortet haben) → Zwischenstand (Rangliste, Überholte tauschen per Animation die Plätze) → Nächste Frage … → Siegerehrung (Treppchen mit Platz 3, 2, 1 nacheinander)

Aufbau

api/index.js       Einstiegspunkt für Vercel
server.js          Lokaler Entwicklungsserver (API + statische Seiten)
src/app.js         Express-App mit allen API-Routen
src/db.js          Postgres-Verbindung
src/auth.js        Registrierung, Login, Sessions (httpOnly-Cookie, bcrypt)
src/quizzes.js     Quiz erstellen/bearbeiten/löschen
src/game.js        Live-Spiele: PIN, QR-Code, Spielablauf, Gäste, Punkte
src/config.js      Spielregeln (Mindestteilnehmer für die Wertung)
src/achievements.js Erfolge: Definitionen, Vergabe am Spielende, API
src/leaderboard.js Bestenliste (gesamt und je Fach)
src/results.js     Statistik und gespeicherte Ergebnisse eingeloggter Spieler
public/            Frontend (reines HTML/CSS/JS, kein Build-Schritt); js/common.js enthält u. a. die Navigation
supabase/          Datenbank-Migrationen

Design, Level und Serie

Die Oberfläche folgt einem weichen Verlaufs-Design mit runden Karten, Level-Anzeige und bunter Navigation. Hinter den Home-Kacheln stehen echte Daten:

• Level: alle 2.000 Level-Punkte (gewertete Quizpunkte plus Lernpunkte) ein Level (POINTS_PER_LEVEL in src/config.js).
• Tage-Serie: aufeinanderfolgende Tage (Europa/Berlin) mit mindestens einem gewerteten Spiel; sie bleibt bestehen, wenn man gestern gespielt hat.
• „+X heute“: gewertete Punkte des heutigen Tages.
• „Aufsteiger!“: der Platz in der Gesamtwertung ist seit dem letzten gewerteten Spiel besser geworden.
• Sammler-Titel: Einsteiger, Entdecker, Sammler, Legende je nach Anzahl der Erfolge.
• Avatare sind der Anfangsbuchstabe auf einem Farbverlauf, Fach-Symbole Emojis.

Freunde

Jeder Nutzer hat eine eindeutige fünfstellige ID (quiz.users.friend_code, 10000–99999, angezeigt als #12345; bei der Registrierung zufällig vergeben, Bestandsnutzer wurden per Migration 013_friends.sql nachträglich versorgt). Unter Profil → Freunde (/friends) sucht man Spieler nach Namen (Teilstück) oder ID (Anfang); Treffer erscheinen beim Tippen als Vorschläge (GET /api/friends/search). Eine Anfrage wird erst mit „Annehmen“ zur Freundschaft; hat die Person schon angefragt, entsteht die Freundschaft sofort. Offene Anfragen zeigt ein roter Zähler am Profil-Symbol der Navigation. Interagieren kann man mit Freunden bisher nur, indem man sie im Quiz-Editor zum gemeinsamen Bearbeiten einlädt – dort werden Freunde beim Tippen vorgeschlagen, und nur Freunde lassen sich einladen (Tabelle quiz.friendships).

This is the beginning of the README. Read the rest at the original. Read the full README ↗