Wichtel Generator – Backend

Backend-Service für eine Wichtel-Generator Web-App. Dieses System stellt sicher, dass über mehrere Runden hinweg keine Wichtel-Paare doppelt vorkommen, solange noch neue Kombinationen mathematisch möglich sind.

Das Backend speichert alle Runden und Paarungen persistent in einer SQLite-Datenbank und stellt eine REST-API über FastAPI bereit.

----------------------FEATURES----------------------

• Wiederholungsfreie Wichtelpaare

  Für die gleiche Teilnehmergruppe werden über mehrere Runden hinweg immer neue Paarungen generiert, solange es mathematisch möglich ist.

• Mathematische Absicherung

  Die maximale Anzahl möglicher eindeutiger Runden wird über Derangements (Subfakultäten) berechnet.

• Persistente Speicherung

  Alle Runden, Teilnehmer und Paarungen werden in SQLite gespeichert.

• REST API (FastAPI)

  Optimiert für Integration in eine Web-App.

----------------------Grundidee----------------------

Wenn dieselbe Gruppe von Personen mehrfach wichtelt, sollen die Paare nicht wiederholt werden.

Dazu wird:

• Aus allen Teilnehmer-E-Mails ein Konstellations-Hash gebildet

• Diese Konstellation erhält einen oder mehrere Cycles

• In jedem Cycle werden so lange neue Runden erzeugt, bis alle möglichen Paarungen ausgeschöpft sind

• Danach wird automatisch ein neuer Cycle gestartet

----------------------Datenbank-Struktur----------------------

• CYCLES

  Eine feste Teilnehmer-Konstellation (über Hash)

• ROUNDS

  Eine einzelne Wichtelrunde innerhalb eines Cycles

• PARTICIPANTS

  Teilnehmer einer bestimmten Runde

• PAIRS

  Wer beschenkt wen in einer Runde

---

Die Datenbank erzwingt:

• kein Selbst-Wichteln

• kein doppelter Schenker

• kein doppelter Empfänger

----------------------API----------------------

Runde erstellen

POST /api/rounds

• Request

    {
      "round_name": "Weihnachten 2025",
      "participants": [
        { "name": "Alice", "email": "alice@mail.com", "wish": "Buch" },
        { "name": "Bob", "email": "bob@mail.com" },
        { "name": "Clara", "email": "clara@mail.com" }
      ]
    }
  

• Response

    {
      "round_id": 12,
      "created_at": "2025-12-01T19:43:10"
    }
  

---

Wichtel aufdecken

POST /api/reveal

• Request

    {
      "email": "alice@mail.com"
    }
  

• Response

    {
      "giver": "Alice",
      "receiver": "Bob",
      "wish": "Schokolade"
    }
  

Wenn eine E-Mail in mehreren Runden vorkommt, gibt die API zuerst eine Auswahlliste zurück.

----------------------Roadmap----------------------

• Token-basierte Reveal-Links

• Mail-Versand

• Ausschlussregeln (Partner, Familie, etc.)

• Deployment