update

.planer/flows.md

@@ -0,0 +1,51 @@
+# Flows: tft
+
+## Flow: Statische Daten laden und bereitstellen
+1. Community-Dragon-Rohdaten werden heruntergeladen und versioniert auf die Festplatte geschrieben — backend/tft/staticdata/fetch.py::fetch_static
+2. Beim Schreiben wird der zuletzt gespeicherte Statikdatensatz über den Pointer wieder eingelesen — backend/tft/staticdata/fetch.py::load_static
+3. Das Rohtext-JSON wird in flache Tabellen für Units, Traits, Items und Augments normalisiert — backend/tft/staticdata/parse.py::parse
+4. Parse wählt die höchste vorhandene Set-Nummer aus Champion-Daten, ergänzt Icon-URLs und leitet Augment-Stufen aus Suffixen ab — backend/tft/staticdata/parse.py::detect_set, backend/tft/staticdata/parse.py::icon_url, backend/tft/staticdata/parse.py::augment_tier
+5. Schadens-Arrays, Schadenstyp und Skalierung einer Champion-Fähigkeit werden aus dem Desc-Markup ermittelt — backend/tft/staticdata/parse.py::resolve_spell
+6. Platzhalter in Tooltip-Texten werden mit Effekt-Werten gefüllt und übriges Markup entfernt — backend/tft/staticdata/parse.py::render_desc
+
+## Flow: Analyse-Artefakt erzeugen
+1. Die TOML-Konstantendatei für ein Set wird eingelesen — backend/tft/constants/loader.py::load_constants
+2. Struktur und Plausibilität der Konstanten werden validiert — backend/tft/constants/loader.py::validate
+3. Das versionierte Analyse-Artefakt wird als Vertrag zwischen Pipeline und Simulation gebaut — backend/tft/model/artifact.py::build
+4. Aus den Unit-Stats wird das 90. Perzentil der Spell-DPS auf 1 Stern ohne Items als Deckelwert berechnet — backend/tft/model/artifact.py::spell_dps_cap, backend/tft/model/statsheet.py::unit_stats
+5. Aus den statischen Items werden die standardmäßig kombinierbaren Items herausgefiltert und auf Komponenten-Schlüssel abgebildet — backend/tft/model/artifact.py::craftable_items, backend/tft/model/artifact.py::recipes
+6. Der Pool an häufig genutzten Basis-Komponenten wird bestimmt — backend/tft/model/artifact.py::component_pool
+7. Augment-Spezifikationen werden katalogweit erzeugt und nach API indiziert — backend/tft/model/artifact.py::_augment_specs, backend/tft/model/augments.py::build_specs
+8. Das fertige Artefakt wird versionsspezifisch als JSON geschrieben und der Latest-Pointer aktualisiert — backend/tft/model/artifact.py::save, backend/tft/paths.py::artifact_dir, backend/tft/paths.py::latest_artifact_pointer
+
+## Flow: Matches crawlen und Endboards extrahieren
+1. Der Riot-API-Key wird aus der Umgebung geladen, wobei `backend/.env` optional eingelesen wird — backend/tft/matches/riot.py::api_key, backend/tft/matches/riot.py::_load_env
+2. Gewertete TFT-Matches von Challengern/GM-Spielern werden gecrawlt und gefiltert in der SQLite-DB persistiert — backend/tft/matches/crawl.py::crawl
+3. Eine SQLite-Verbindung wird hergestellt und das Schema initialisiert — backend/tft/db.py::connect
+4. Alle noch nicht verarbeiteten Roh-Matches werden gelesen, ihre Endboard-Zeilen extrahiert und persistiert — backend/tft/matches/extract.py::extract_all
+5. Pro Teilnehmer werden die relevanten Felder in Endboard-Tupel überführt — backend/tft/matches/extract.py::extract_match
+6. Der zweistellige Patch wird aus dem `game_version`-String abgeleitet — backend/tft/matches/extract.py::patch_of
+7. IDs in Endboard-Zeilen, die nicht in den statischen Daten vorkommen, werden als Patch-Drift gezählt — backend/tft/matches/extract.py::validate_ids
+
+## Flow: Multiplikatoren aus Endboards lernen
+1. Endboard-Zeilen eines Sets werden aus einer SQL-Verbindung gelesen — backend/tft/model/learn.py::learn_from_db
+2. Endboard-Zeilen werden zu placementsbezogenen Multiplikatoren für Einheiten, Traits, Items, Augments und Paaren aggregiert — backend/tft/model/learn.py::learn
+3. Pro Eintrag wird ein um Bayessche Schrumpfung zentrierter Stärke-Multiplikator aus den Platzierungen berechnet — backend/tft/model/learn.py::_multiplier
+
+## Flow: Headless-Simulation ausführen
+1. Die vollständige Stage-/Round-Folge eines Spiels inklusive Augment-Markierung wird erzeugt — backend/tft/sim/rounds.py::schedule
+2. n headless Spiele werden mit der gewählten Policy ausgeführt und Platzierungen aggregiert — backend/tft/sim/autoplay.py::run
+3. Entweder wird ein Spiel ohne Eingriff zu Ende gespielt — backend/tft/sim/autoplay.py::play_afk
+4. Oder ein Spiel wird mit der Econ-Policy zu Ende gespielt — backend/tft/sim/autoplay.py::play_econ
+5. Eine vollständige Partie wird als endliche Zustandsmaschine über Runden und Kämpfe orchestriert — backend/tft/sim/game.py::Game
+6. Die PvP-Paarungen der lebenden Spieler werden ermittelt — backend/tft/sim/game.py::pair_players, backend/tft/sim/game.py::pair_players
+7. Pro Paarung wird ein deterministischer Kampf zweier Teams eventbasiert simuliert — backend/tft/sim/combat.py::fight, backend/tft/sim/combat.py::FightResult
+8. Der Schaden, den ein Spieler nach der Runde erhält, wird abhängig von Stage und Überlebenden berechnet — backend/tft/sim/combat.py::player_damage
+
+## Flow: Spielzustand über die API beantworten
+1. Eine neue TFT-Spiellauf-Instanz wird erstellt und im globalen Register registriert — backend/tft/api/app.py::new_game
+2. Für eine Aktions-Anfrage werden benötigte statische Set-Daten und Konfigurationswerte geladen — backend/tft/api/app.py::_load_game_deps
+3. Die Aktions-Anfrage wird interpretiert und an die passende Game-Methode weitergeleitet — backend/tft/api/app.py::action, backend/tft/api/app.py::ActionRequest
+4. Der Spielzustand der Instanz wird als JSON-Bild inklusive Brett, Bank, Shop, Traits und Gegnern serialisiert — backend/tft/api/app.py::state, backend/tft/api/app.py::serialize
+5. Interne Einheit-Darstellungen werden in die API-Antwortstruktur projiziert — backend/tft/api/app.py::unit_view
+6. Als Außenwirkung wird zusätzlich der Aufstiegs-Hinweis in die nächste Sternstufe bei weiterem Kauf berechnet — backend/tft/api/app.py::upgrade_hint