update

.planer/einheiten/backend__tft__sim__economy.py.md

@@ -0,0 +1,59 @@
+# Einheiten: backend/tft/sim/economy.py
+stand: f41ac76b5789
+
+## backend/tft/sim/economy.py::interest
+beschreibung: Berechnet die passiven Zinserträge auf Basis des aktuellen Goldstands.
+input: aktueller Goldstand `gold` und die Konfiguration `cfg`
+output: gekappter Zinsbetrag gemäß Konfigurationsobergrenze
+entscheidungen:
+- Der Zins wird in 10er-Schritten gewährt und auf einen Maximalwert gedeckelt.
+  beleg: "min(gold // 10 * g[\"interest_per_10\"], g[\"interest_cap\"])"
+kanten:
+- wird-genutzt-von: backend/tft/sim/economy.py::round_income
+
+## backend/tft/sim/economy.py::streak_gold
+beschreibung: Liefert den Streak-Bonus auf Basis der absoluten Streaklänge aus einer gestaffelten Konfigurationstabelle.
+input: aktuelle Streaklänge `streak` und die Konfiguration `cfg`
+output: höchster anwendbarer Streak-Bonuswert (oder 0)
+entscheidungen:
+- Es wird der größte passende Schwellenwert verwendet, da spätere Iterationen frühere überschreiben.
+  beleg: "if abs(streak) >= min_streak:"
+- Streaks werden symmetrisch auf ihre Länge betrachtet, sodass Sieg- und Niederlagenserien gleichbehandelt werden.
+  beleg: "if abs(streak) >= min_streak:"
+kanten:
+- wird-genutzt-von: backend/tft/sim/economy.py::round_income
+
+## backend/tft/sim/economy.py::round_income
+beschreibung: Aggregiert die gesamten Goldeinnahmen einer Runde aus Grundeinkommen, Zinsen, Streak-Bonus und Siegbonus.
+input: Goldstand `gold`, Streak `streak`, Siegstatus `won`, Rundenlabel `round_label` und Konfiguration `cfg`
+output: Gesamtes Goldeinkommen dieser Runde als Summe aller Komponenten
+entscheidungen:
+- Frühe Runden erhalten ein spezielles Grundeinkommen, andere fallen auf den Standardwert zurück.
+  beleg: "g[\"early_income\"].get(round_label, g[\"base_income\"])"
+- Nur bei einem Rundensieg wird der Siegbonus addiert.
+  beleg: "if won:"
+kanten:
+- ruft-auf: backend/tft/sim/economy.py::interest
+- ruft-auf: backend/tft/sim/economy.py::streak_gold
+
+## backend/tft/sim/economy.py::xp_to_next
+beschreibung: Liefert die XP-Schwelle bis zum nächsten Level oder signalisiert das Erreichen des Maximallevels.
+input: aktuelles Level `level` und die Konfiguration `cfg`
+output: benötigte XP für das nächste Level, oder `None` am Maximallevel
+entscheidungen:
+- Am oder über dem Maximallevel wird `None` zurückgegeben, um einen weiteren Aufstieg zu verhindern.
+  beleg: "if level >= xp[\"max_level\"]:"
+kanten:
+- wird-genutzt-von: backend/tft/sim/economy.py::apply_xp
+
+## backend/tft/sim/economy.py::apply_xp
+beschreibung: Wendet gewonnene XP auf einen Spieler an und levelt ihn automatisch so weit wie möglich auf.
+input: aktuelles Level `level`, aktuelle XP `xp`, hinzugewonnene XP `gained` und Konfiguration `cfg`
+output: aktualisiertes Level und verbleibende XP nach möglichen Levelaufstiegen
+entscheidungen:
+- Mehrere Levelaufstiege werden in einer Schleife konsumiert, solange XP reicht und das Maximallevel nicht erreicht ist.
+  beleg: "while (need := xp_to_next(level, cfg)) is not None and xp >= need:"
+- Beim Erreichen des Maximallevels werden verbleibende XP verworfen, um Überlauf zu vermeiden.
+  beleg: "if level >= cfg[\"xp\"][\"max_level\"]:"
+kanten:
+- ruft-auf: backend/tft/sim/economy.py::xp_to_next