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