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).

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗