update

.planer/einheiten/backend__tft__api__app.py.md

@@ -0,0 +1,107 @@
+# Einheiten: backend/tft/api/app.py
+stand: f41ac76b5789
+
+## backend/tft/api/app.py::ActionRequest
+beschreibung: Definiert das Pydantic-Schema für eingehende Aktions-Requests einer TFT-Spielpartie.
+input: HTTP-Request-Body mit den Aktions-Feldern action, slot, where, idx, item_idx, board_idx, choice
+output: Ein ActionRequest-Modell mit validierten, optional typisierten Aktions-Parametern
+entscheidungen:
+- Sämtliche Aktions-Parameter außer action sind als optional deklariert
+  beleg: "slot: int | None = None"
+- Die Modell-Klasse verwendet Pydantic-BaseModel zur automatischen Validierung
+  beleg: "class ActionRequest(BaseModel):"
+kanten:
+
+## backend/tft/api/app.py::health
+beschreibung: Stellt einen Health-Check-Endpunkt zur Verfügung, der den Betriebszustand des Dienstes meldet.
+input: HTTP-GET-Aufruf auf /health
+output: Ein JSON-Objekt mit status="ok"
+entscheidungen:
+- Der Endpunkt ist über den Pfad /health erreichbar
+  beleg: "@app.get(\"/health\")"
+- Der Status wird statisch als "ok" zurückgegeben
+  beleg: "return {\"status\": \"ok\"}"
+kanten:
+
+## backend/tft/api/app.py::_load_game_deps
+beschreibung: Lädt die für eine Spielsitzung benötigten statischen Set-Daten und Konfigurationswerte.
+input: Keine Argumente; liest den Static-Pointer aus dem Dateisystem
+output: Ein Tupel aus geladenem Artifact-Set und Konfigurationswerten
+entscheidungen:
+- Bei fehlendem Static-Pointer wird ein HTTP-503-Fehler ausgelöst
+  beleg: "raise HTTPException(503, \"no static data: run `tft.cli fetch-static` first\")"
+- Die benötigten Submodule werden lokal erst zur Laufzeit importiert
+  beleg: "from tft.constants.loader import load_constants"
+kanten:
+
+## backend/tft/api/app.py::new_game
+beschreibung: Erstellt eine neue TFT-Spiellauf-Instanz und registriert sie im globalen Spiellauf-Register.
+input: Optionaler Seed-Wert für die Initialisierung des Zufallsgenerators
+output: Ein JSON-Objekt mit der frisch vergebenen game_id und dem serialisierten Spielzustand
+entscheidungen:
+- Die Spiele werden in einem prozessglobalen Dictionary GAMES gehalten
+  beleg: "GAMES[game_id] = Game(artifact, cfg, seed=seed)"
+- Die game_id ist eine 8-stelligen Hex-Kürzel einer UUID
+  beleg: "game_id = uuid.uuid4().hex[:8]"
+kanten:
+
+## backend/tft/api/app.py::state
+beschreibung: Liefert den serialisierten Spielzustand einer bestehenden Spiellauf-Instanz.
+input: Eine game_id aus der URL
+output: Ein JSON-Objekt mit dem Spielzustand oder ein 404-Fehler
+entscheidungen:
+- Unbekannte Spiele führen zu einem 404-Fehler statt zu einem leeren Zustand
+  beleg: "raise HTTPException(404, \"unknown game\")"
+- Der Endpunkt ist als GET auf /api/game/{game_id} definiert
+  beleg: "@app.get(\"/api/game/{game_id}\")"
+kanten:
+
+## backend/tft/api/app.py::action
+beschreibung: Interpretiert eine Aktions-Anfrage und leitet sie an die passende Game-Methode weiter.
+input: Eine game_id sowie ein ActionRequest mit Aktionstyp und Parametern
+output: Ein serialisierter Spielzustand nach Ausführung oder ein 4xx-Fehler
+entscheidungen:
+- Unbekannte Aktionen werden als 400-Fehler abgewiesen
+  beleg: "raise HTTPException(400, f\"unknown action {req.action}\")"
+- Ungültige Aktionen der Domäne werden als 400-Fehler übersetzt
+  beleg: "except InvalidAction as e:"
+- Fehlende Parameter werden als 400-Fehler mit Hinweis auf die Aktion gemeldet
+  beleg: "raise HTTPException(400, f\"missing parameters for action {req.action}\")"
+kanten:
+
+## backend/tft/api/app.py::upgrade_hint
+beschreibung: Berechnet, in welche Sternstufe eine Einheit durch einen weiteren Kauf aufsteigen würde.
+input: Das Game-Objekt sowie der api_name einer Einheit
+output: 0 für kein Upgrade, 2 für einen 2-Sterne- oder 3 für einen 3-Sterne-Aufstieg
+entscheidungen:
+- Bereits 3-Sterne-Einheiten werden vom Upgrade-Pfad ausgeschlossen
+  beleg: "if u[\"api_name\"] == api and u[\"stars\"] < 3"
+- Höhere Sterne zählen mit Stern-Eskalation als 3^(s-1) Kopien
+  beleg: "sum(3 ** (u[\"stars\"] - 1) for u in owned)"
+kanten:
+
+## backend/tft/api/app.py::unit_view
+beschreibung: Projiziert eine interne Einheit-Darstellung in die API-Antwortstruktur.
+input: Ein Game-Objekt sowie eine Einheit-Dictionary-Repräsentation
+output: Ein JSON-Objekt mit Anzeigename, Kosten, Sternen, Traits, Icon und getragenen Items
+entscheidungen:
+- Fehlende Anzeigenamen fallen auf den api_name zurück
+  beleg: "\"name\": info.get(\"name\", u[\"api_name\"])"
+- Item-Namen und -Icons werden tolerant gegen fehlende Einträge ausgelesen
+  beleg: "game.artifact[\"static\"][\"items\"].get(i, {}).get(\"name\", i)"
+kanten:
+
+## backend/tft/api/app.py::serialize
+beschreibung: Erzeugt das vollständige JSON-Spielbild inklusive Brett, Bank, Shop, Traits und Gegnern.
+input: Ein Game-Objekt der laufenden Simulation
+output: Ein umfangreiches Dictionary, das alle UI-relevanten Spielzustandsdaten bündelt
+entscheidungen:
+- Die Trait-Liste wird absteigend nach Tier und Count sortiert
+  beleg: "key=lambda x: (-x[\"tier\"], -x[\"count\"])"
+- Gegner werden absteigend nach HP sortiert dargestellt
+  beleg: "key=lambda x: -x[\"hp\"]"
+- Das Log wird auf die letzten acht Einträge begrenzt
+  beleg: "\"log\": game.log[-8:]"
+- Aktive Trait-Tiers werden aus Brett-Einheiten berechnet
+  beleg: "tiers = active_trait_tiers(game.board, static[\"traits\"], static[\"units\"])"
+kanten: