Virtuelle Lostrommel

Virtuelle Lostrommel für Messeauftritte der Firma B1 Systems

Beschreibung

Webanwendung um die physische Lostrommel auf Messeständen zu ersetzen. Teilnehmende können sich über einen Link/QR-Code registrieren, Teilnahmebedingungen einsehen und zustimmen, und sich optional am Newsletter anmelden. Die Registrierung wird über eine E-Mail mit Linkklick bestätigt. Danach erhalten die Teilnehmenden einen Gewinncode, mit dem sie der Losziehung beiwohnen können.

Die Präsentation der Gewinnlose erfolgt dann auch durch die virtuelle Lostrommel.

Es können beliebig viele Gewinnspiele parallel angelegt werden und laufen.

Vorteile im Vergleich zur physischen Lostrommel ist ein höherer Zufallsfaktor, weniger Vorbereitung nötig für Standleute, und eine höhere Wahrscheinlichkeit, dass wir funktionierende Mailaddressen kriegen.

Benutzung

• Gewinnspiel unter /admin/dashboard anlegen (mit Name, Start, Ende, Messe und case-sensitiven Kürzel)
• QR-Code fürs Teilnehmen findet sich dann auch im Dashboard
• Direktlink zur Gewinnspielteilnahme: /register/[Gewinnspielkürzel]
• Link zur Gewinnspiel-Landingpage: /[Gewinnspielkürzel]
• Gewinnspiel nach Zeit beenden oder im Dashboard, dann in Gewinnspielübersicht Präsentation der Ergebnisse starten

Setup

Requirements

Benötigt u.a. folgende Pakete:

• sqlite3
• Python
  • fastapi[all]
  • sqlalchemy

In pyproject.toml sind alle benötigten Module hinterlegt

Lokales Setup mit Container

1. .env aus .env.dist kopieren und befüllen
2. export TAG=[...] mit dem gewünschten Tag (feste Version, latest, oder Tag von Feature-Branch)
3. podman compose up

Wenn "403 Unauthorized": podman login registry.intern.b1-systems.de

Installation & Setup via uv

1. Installation von uv
   • pip install uv
2. Installation der benötigten Pakete
   • uv sync
3. .env aus .env.dist kopieren und befüllen
4. je nachdem ob Dev-Setup oder Nutzung existierender Mailserver: mailpit starten:
   • mailpit-Docker-Setup, dann ist standardmäßig 1025 der SMTP-Port und localhost oder 0.0.0.0 die Mailserveradresse fürs .env-File
5. Lostrommel-Server starten
   • uv run uvicorn app.main:app --reload
   • --host 0.0.0.0 anhängen, um mit Geräten im selben Netzwerk auf Seite zugreifen zu können (braucht http://[lokale IP]:8000 als HOST in .env)

Entwicklung

Übersetzungen (siezen und duzen)

Sämtliche Strings, bei denen man sich zwischen formeller und informeller Anrede entscheiden müsste, werden in beiden Varianten bereitgestellt. Dafür nutzen wir pybabel und gettext, mit dem Shorthand _("...") für übersetzbare Strings. Die Entscheidung zwischen formaler und informeller Ansprache findet auf Gewinnpsielebene statt. Dafür wird das Toggle "Siezen" in der Gewinnspielerstellung benutzt.

Nach Änderungen, folgende Schritte ausführen, damit die Übersetzungsdateien in translations/ geupdated werden und man dann die Sie-Version ergänzen kann:

pybabel extract -F babel.cfg -o translations/messages.pot .
pybabel update -i translations/messages.pot -d translations/
# ggf. neue Übersetzungen hinzufügen / Anpassungen machen
pybabel compile -d translations # nur nötig für lokales Ausführen, der Schritt wird auch im Containerbau ausgeführt

Tests

Im Verzeichnis tests/ finden sich Ende-zu-Ende-Tests für die virtuelle Lostrommel. Diese werden bei Commits und Merge Requests in das GitLab-Repo automatisiert ausgeführt. Um sie während der Entwicklung auch lokal auszuführen:

1. in .env den IMAP-Port des Mailservers MAIL_IMAP_PORT eintragen (für mailpit standardmäßig Port 8025)
2. die Test-Requirements mit uv sync --only-group test installieren
3. uv run pytest "." --order-dependencies

Die Tests sind nicht komplett unabhängig voneinander, um vielfaches Erstellen von neuen Gewinnspielen und Anlegen neuer Teilnehmender zu verhindern. Daher werden pytest-order und pytest-dependency verwendet, um die Tests in verschiedene Stufen zu sortieren und Abhängigkeiten wie Gewinnspielerstellung > Gewinnspielregistrierung abzubilden.

Hinweise

Idee und erster Prototyp von Corbinian Koch im Rahmen seines Abschlussprojekts