# 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).