diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d98617 --- /dev/null +++ b/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 \ No newline at end of file