README added

README.md

@@ -0,0 +1,134 @@
+
+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