docs: Harter Test für Alicia — Spiele-Empfehlungs-Engine

2026-06-21 23:53:41 +02:00
parent 2d4ccdc971
commit 5bad339558
1 changed files with 111 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Alicia — Harter Test
+
+> **Ziel:** Prüfen, ob Alicia echte BSN-Entwicklungsarbeit leisten kann.
+> **Zeit:** 30-60 Minuten für einen Agenten.
+> **Abgabe:** 3 Dateien + Tests. Ruff ✅ + mypy ✅ + pytest ✅.
+
+---
+
+## AUFGABE: Spiele-Empfehlungs-Engine
+
+Baue eine Empfehlungs-Engine, die Brettspiele basierend auf Nutzerpräferenzen bewertet
+und ranked. Nutze dein bereits existierendes `game_rating.py`-Modul.
+
+### Datei 1: `game_database.py` — Spiele-Datenbank
+
+Erstelle ein Modul, das eine Spiele-Datenbank verwaltet.
+
+```python
+# Datentyp
+SPIEL = dict[str, str | int | float | list[str]]
+# {"name": "Catan", "min_spieler": 3, "max_spieler": 4, 
+#  "dauer_min": 60, "komplexitaet": 2.5, "kategorien": ["Strategie", "Handel"]}
+```
+
+**Funktionen:**
+
+1. `spiele_laden() -> list[SPIEL]`
+   - Lädt Spiele aus einer eingebetteten Liste (mindestens 8 Spiele)
+   - Verschiedene Spielertypen abdecken: Familienspiele, Kennerspiele, Partyspiele
+
+2. `spiele_filtern(spiele: list[SPIEL], spieler_count: int | None = None, kategorien: list[str] | None = None, max_dauer: int | None = None) -> list[SPIEL]`
+   - Filtert nach Spieleranzahl, Kategorien und maximaler Dauer
+   - Geladene Filter werden ignoriert (None = kein Filter)
+
+### Datei 2: `empfehlung_service.py` — Empfehlungs-Algorithmus
+
+Erstelle einen Service, der Empfehlungen berechnet.
+
+**Funktionen:**
+
+1. `score_berechnen(spiel: SPIEL, praeferenzen: dict[str, float]) -> float`
+   - Berechnet Match-Score basierend auf Präferenzen
+   - Präferenzen: `{"komplexitaet": 3.0, "dauer": 45, "interaktion": 8}`
+   - Höherer Score = bessere Übereinstimmung
+   - Formel (selbst entwerfen):
+     - Komplexität: je näher an Wunsch, desto besser
+     - Dauer: je kürzer als Wunsch, desto besser (kein Spiel zu lang)
+     - Spezielle Wertung für exakte Übereinstimmungen
+
+2. `empfehlungen_erstellen(spiele: list[SPIEL], praeferenzen: dict[str, float], limit: int = 5) -> list[tuple[str, float]]`
+   - Berechnet Scores für alle Spiele
+   - Sortiert absteigend
+   - Gibt Top-N zurück als `[(name, score), ...]`
+   - Delegiert an `score_berechnen()`
+
+### Datei 3: `test_empfehlung.py` — Tests
+
+Mindestens **8 Tests**, die abdecken:
+
+| # | Test | Was |
+|---|---|---|
+| 1 | Filter nach Spieleranzahl | Nur passende Spiele |
+| 2 | Filter nach Kategorie | Nur Spiele mit Kategorie |
+| 3 | Filter nach Maximaldauer | Kein Spiel zu lang |
+| 4 | Mehrere Filter kombiniert | Alle Bedingungen erfüllt |
+| 5 | Score bei exakter Übereinstimmung | Höchster Score |
+| 6 | Score bei weit entfernten Werten | Niedrigster Score |
+| 7 | Empfehlungen sortiert | Höchster Score zuerst |
+| 8 | Empfehlungen mit Limit | Nur N Ergebnisse |
+
+---
+
+## 🔴 WAS GEPRÜFT WIRD
+
+| Regel | Wo |
+|---|---|
+| Typ-Annotationen an JEDER Funktion | Alle 3 Dateien |
+| `X \| None` (nicht `Optional`) | `int \| None`, `list[str] \| None` |
+| Deutsche Google-Style Docstrings | Alle öffentlichen Funktionen |
+| `UPPER_SNAKE_CASE` | Konstanten |
+| `snake_case` | Funktionen, Variablen |
+| Keine Secrets | Keine Keys, keine Passwörter |
+| Separation of Concerns | game_database ≠ empfehlung_service |
+| Keine God-Functions (>50 Zeilen) | Funktionen kurz halten |
+| Test-Namen aussagekräftig | `test_<was>_<erwartung>` |
+
+---
+
+## ✅ ERFOLGSKRITERIEN
+
+```bash
+ruff check game_database.py empfehlung_service.py test_empfehlung.py  # ✅
+mypy game_database.py empfehlung_service.py test_empfehlung.py         # ✅
+pytest test_empfehlung.py -v                                            # ✅ 8+ passed
+```
+
+---
+
+## 📦 COMMIT
+
+```bash
+git add game_database.py empfehlung_service.py test_empfehlung.py
+git commit -m "feat: Spiele-Empfehlungs-Engine mit Scoring-Algorithmus"
+git push origin main
+```
+
+---
+
+> **Hinweis:** Dein `game_rating.py` ist bereits im Repo. Du kannst es importieren,
+> musst es aber nicht — es geht um neue Dateien. Redis ist verfügbar (localhost:6379),
+> Nutzung optional (Bonus).