update

.planer/einheiten/backend__tft__model__statsheet.py.md

@@ -0,0 +1,95 @@
+# Einheiten: backend/tft/model/statsheet.py
+stand: f41ac76b5789
+
+## backend/tft/model/statsheet.py::_empty_acc
+beschreibung: Liefert ein frisches Sammel-Dictionary mit allen bekannten Stat-Buff-Akkumulatoren auf 0.0 initialisiert.
+input: keine Argumente
+output: ein `dict` mit 12 numerischen Stat-Feldern (z. B. `ad_pct`, `ap_flat`, `hp_pct`).
+entscheidungen:
+- Alle Felder werden explizit auf 0.0 gesetzt, damit Akkumulatoren ohne Vorbelastung starten.
+  beleg: "{\"ad_pct\": 0.0, \"ap_flat\": 0.0, \"as_pct\": 0.0, \"hp_flat\": 0.0,"
+- Es wird genau ein gemeinsames Akkumulator-Schema für Items und Trait-Buffs verwendet.
+  beleg: "return {\"ad_pct\": 0.0, \"ap_flat\": 0.0, \"as_pct\": 0.0, \"hp_flat\": 0.0,"
+kanten:
+- wird-genutzt-von: backend/tft/model/statsheet.py::_apply_item_effects
+- wird-genutzt-von: backend/tft/model/statsheet.py::trait_buffs
+- wird-genutzt-von: backend/tft/model/statsheet.py::unit_stats
+
+## backend/tft/model/statsheet.py::_apply_item_effects
+beschreibung: Überträgt die modellierten Item-Effekte aus dem Datenkatalog in den Stat-Akkumulator und normalisiert Werteinheiten.
+input: `item_apis` (zu applizierende Item-IDs), `static_items` (Item-Katalog), `acc` (Stat-Akkumulator)
+output: keine Rückgabe; `acc` wird in-place um Item-Boni angereichert.
+entscheidungen:
+- Unbekannte oder `None`-Effekte werden bewusst ignoriert, um bespoke Mechanik nicht zu modellieren.
+  beleg: "if val is None:"
+- Roh-Listenwerte werden via `_fraction` normalisiert, während flache Skalierungen direkt addiert werden.
+  beleg: "elif key in (\"BonusDamage\", \"DamageAmp\"):"
+- Prozent-Keys (`AS`, `CritChance`) werden durch 100 geteilt, weil sie als Prozentzahl geliefert werden.
+  beleg: "elif key == \"AS\":"
+- `MAPPED_ITEM_KEYS` definiert die Menge der modellierten Effekte als vertragliche Whitelist.
+  beleg: "MAPPED_ITEM_KEYS = (\"AD\", \"AP\", \"AS\", \"CritChance\", \"Health\", \"Armor\","
+kanten:
+- nutzt: backend/tft/model/statsheet.py::_fraction
+- wird-genutzt-von: backend/tft/model/statsheet.py::unit_stats
+
+## backend/tft/model/statsheet.py::item_is_modeled
+beschreibung: Entscheidet anhand der modellierten Effekt-Whitelist, ob ein Item überhaupt in die Berechnung einfließt.
+input: `item_info` (Item-Datensatz mit `effects`)
+output: `bool`, `True` sobald mindestens ein modellierter Key einen Nicht-`None`-Wert hat.
+entscheidungen:
+- Nur Werte != None zählen, da `None` als „nicht angegeben" interpretiert wird.
+  beleg: "return any(effects.get(k) is not None for k in MAPPED_ITEM_KEYS)"
+- Die modellierten Keys sind als Modul-Konstante `MAPPED_ITEM_KEYS` zusammengefasst.
+  beleg: "MAPPED_ITEM_KEYS = (\"AD\", \"AP\", \"AS\", \"CritChance\", \"Health\", \"Armor\","
+kanten:
+- nutzt: backend/tft/model/statsheet.py::_apply_item_effects
+
+## backend/tft/model/statsheet.py::_fraction
+beschreibung: Normalisiert cdragon-Werte, die mal als Fraction (0.15) und mal als Prozentzahl (15.0) vorliegen, auf einen einheitlichen Bruch.
+input: `value` (float)
+output: `float` im Bereich [0, 1] (Fraction).
+entscheidungen:
+- Schwellwert 1.0 entscheidet, ob ein Wert als bereits normalisierte Fraction gilt.
+  beleg: "return value if abs(value) <= 1.0 else value / 100"
+- Beträge werden verglichen, damit auch negative Fraktionen korrekt behandelt werden.
+  beleg: "return value if abs(value) <= 1.0 else value / 100"
+kanten:
+- wird-genutzt-von: backend/tft/model/statsheet.py::_apply_item_effects
+- wird-genutzt-von: backend/tft/model/statsheet.py::trait_buffs
+
+## backend/tft/model/statsheet.py::trait_buffs
+beschreibung: Zerlegt Trait-Variablennamen in Tokens und leitet daraus teamweite Stat-Buffs sowie die Liste der erkannten Traits ab.
+input: `active_tiers` (aktive Trait-Breakpoints), `static_traits` (Trait-Katalog)
+output: Tupel `(buffs, recognized)` mit Akkumulator-Dictionary und Set erkannter Trait-IDs.
+entscheidungen:
+- Mechanik-Parameter werden über eine Token-Blacklist früh aussortiert.
+  beleg: "if tokens & _SKIP_TOKENS or name.startswith(\"{\"):"
+- `ap`-Tokens werden mit `* 100` auf den flachen AP-Konventionen aufsummiert.
+  beleg: "elif \"ap\" in tokens:"
+- Variablen ohne numerischen Wert werden übersprungen, um Token-Mismatches zu vermeiden.
+  beleg: "if value is None or not isinstance(value, (int, float)):"
+- Nur Traits, bei denen mindestens eine Variable als Buff gemappt wurde, landen in `recognized`.
+  beleg: "if matched:"
+kanten:
+- nutzt: backend/tft/model/statsheet.py::_empty_acc
+- nutzt: backend/tft/model/statsheet.py::_fraction
+- nutzt: backend/tft/model/statsheet.py::_TOKEN_RE
+
+## backend/tft/model/statsheet.py::unit_stats
+beschreibung: Berechnet das effektive Kampfprofil (eHP, Gesamt-DPS, Spell-DPS) einer Unit aus Basiswerten, Sternenmultiplikatoren, Team-Buffs und Items.
+input: `unit` (Champion-Daten), `stars`, `item_apis`, `static_items`, `team_buffs`, `role`, optional `spell_cap`
+output: `dict` mit den Schlüsseln `ehp`, `dps` und `spell_dps`.
+entscheidungen:
+- HP und AD skalieren über `HP_STAR_MULT` bzw. `AD_STAR_MULT` je nach Sternenlevel.
+  beleg: "hp = (stats.get(\"hp\") or 0) * HP_STAR_MULT ** (stars - 1)"
+- eHP kombiniert Rüstung/MR und Schadensreduktion multiplikativ.
+  beleg: "ehp = hp * (1 + (armor + mr) / 200) * (1 + acc[\"dr\"])"
+- Die Cast-Rate wird durch `CAST_RATE_CAP` gedeckelt, um Ausreißer zu verhindern.
+  beleg: "CAST_RATE_CAP,"
+- Spell-DPS ist auf `SPELL_AUTO_CAP` mal eigene Auto-DPS begrenzt, mit optionalem Floor.
+  beleg: "limit = SPELL_AUTO_CAP * auto_dps"
+- Team-Buffs und Item-Effekte werden in `_empty_acc` zusammengeführt, um Bonus-Stats konsistent anzureichern.
+  beleg: "acc = _empty_acc()"
+kanten:
+- nutzt: backend/tft/model/statsheet.py::_empty_acc
+- nutzt: backend/tft/model/statsheet.py::_apply_item_effects