tft/.planer/einheiten/backend__tft__model__statsheet.py.md

# 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