update

.planer/einheiten/backend__tft__model__augments.py.md

@@ -0,0 +1,46 @@
+# Einheiten: backend/tft/model/augments.py
+stand: f41ac76b5789
+
+## backend/tft/model/augments.py::_num
+beschreibung: Liest einen numerischen Effekt-Wert aus einem Dict über eine Liste bevorzugter Schlüssel.
+input: ein `effects`-Dict und ein Tupel von Schlüsselnamen
+output: den ersten positiven Zahlenwert oder `None`, falls keiner passt
+entscheidungen:
+- Nur der erste positive Treffer zählt; Null und negative Werte werden übersprungen.
+  beleg: "if isinstance(val, (int, float)) and val > 0:"
+- Es wird strikt zwischen echten Zahlen und Nicht-Zahlen gefiltert, bevor der Wert gilt.
+  beleg: "if isinstance(val, (int, float)) and val > 0:"
+- Fehlt jeder passende Schlüssel, signalisiert die Funktion das durch `None`.
+  beleg: "return None"
+kanten:
+- wird-genutzt-von: backend/tft/model/augments.py::build_spec
+
+## backend/tft/model/augments.py::build_spec
+beschreibung: Zerlegt ein einzelnes Augment in mechanisch anwendbare Atome aus Beschreibung und Effects-Block.
+input: ein Augment-Dict (`api`, `desc`, `effects`) und das `static_units`-Verzeichnis
+output: ein Dict mit `atoms`-Liste und `offerable`-Flag
+entscheidungen:
+- Ein Augment gilt nur dann als „offerable", wenn die Beschreibung lang genug und frei von Platzhaltern ist.
+  beleg: "offerable = len(desc) >= 10 and \"_Desc\" not in desc and \"@\" not in desc"
+- Beim Spieler-HP-Atom wird der Effects-Wert bevorzugt, sonst der Regex-Treffer aus der Beschreibung.
+  beleg: "\"amount\": int(_num(effects, PLAYER_HP_KEYS) or m.group(1))"
+- Team-Stat-Buffs werden nur übernommen, wenn die Beschreibung unkonditional ist.
+  beleg: "if TEAM_RE.search(desc) and not CONDITIONAL_RE.search(desc):"
+- Fraktionswerte werden zur Vergleichbarkeit mit `statsheet` über `_fraction` normalisiert.
+  beleg: "value = _fraction(val)"
+kanten:
+- ruft-auf: backend/tft/model/augments.py::_num
+- nutzt: backend/tft/model/statsheet.py::_fraction
+- wird-genutzt-von: backend/tft/model/augments.py::build_specs
+
+## backend/tft/model/augments.py::build_specs
+beschreibung: Wendet `build_spec` auf alle Augmente eines Katalogs an und indiziert das Ergebnis nach API.
+input: ein `static_augments`-Dict und das `static_units`-Verzeichnis
+output: ein Dict, das jeder API ihr `build_spec`-Ergebnis zuordnet
+entscheidungen:
+- Die Funktion ist eine reine Dictionary-Komprehension über den gesamten Katalog.
+  beleg: "return {api: build_spec(aug, static_units) for api, aug in static_augments.items()}"
+- Die Schlüssel des Eingabe-Dicts werden unverändert als API-Schlüssel übernommen.
+  beleg: "for api, aug in static_augments.items()"
+kanten:
+- ruft-auf: backend/tft/model/augments.py::build_spec