update

.planer/einheiten/backend__tft__matches__extract.py.md

@@ -0,0 +1,61 @@
+# Einheiten: backend/tft/matches/extract.py
+stand: f41ac76b5789
+
+## backend/tft/matches/extract.py::patch_of
+beschreibung: Leitet den zweistelligen Versions-Patch (z. B. „16.14") aus einem beliebigen `game_version`-String ab.
+input: Ein `game_version`-String mit beliebigen Präfixen oder Trennzeichen.
+output: Der Patch-Anteil als String der Form „x.y".
+entscheidungen:
+- Iteriert über Tokens statt blind zu splitten, um an einen tatsächlichen `x.y`-Token zu gelangen.
+  beleg: "for token in game_version.replace(\"(\", \" \").split():"
+- Übernimmt nur die ersten beiden Punkt-Segmente und ignoriert alles dahinter.
+  beleg: "return \".\".join(digits.split(\".\")[:2])"
+- Bevorzugt ein gefundes numerisches Token gegenüber dem Fallback auf das letzte whitespace-getrennte Wort.
+  beleg: "digits = token"
+kanten:
+- wird-genutzt-von: backend/tft/matches/extract.py::extract_match
+
+## backend/tft/matches/extract.py::extract_match
+beschreibung: Überführt ein einzelnes rohes Match-Diktat in eine Liste von Endboard-Zeilen, indem es pro Teilnehmer die relevanten Felder in ein Tupel schreibt.
+input: Ein `match`-Dictionary gemäß Riot-Match-Schema.
+output: Eine Liste von Tupeln mit Match-ID, PUUID, Set-Nummer, Patch, Platzierung, Level, letzter Runde, Restgold und JSON-serialisierten Units/Traits/Augments.
+entscheidungen:
+- Serialisiert verschachtelte Strukturen (Units, Traits, Augments) vor dem Schreiben als JSON-String, um eine flache Tupel-Form zu behalten.
+  beleg: "json.dumps(p[\"units\"]),"
+- Liefert bei fehlendem `augments`-Feld eine leere Liste statt einen Fehler.
+  beleg: "json.dumps(p.get(\"augments\", [])),"
+- Bezieht den Patch je Match zentral aus `info` und nicht pro Teilnehmer neu berechnet.
+  beleg: "patch = patch_of(info[\"game_version\"])"
+kanten:
+- ruft-auf: backend/tft/matches/extract.py::patch_of
+- wird-genutzt-von: backend/tft/matches/extract.py::extract_all
+
+## backend/tft/matches/extract.py::validate_ids
+beschreibung: Zählt in den Endboard-Zeilen IDs (Units, Items, Traits, Augments), die nicht in den statischen Daten vorkommen, als Patch-Drift-Kanarienvogel.
+input: Eine Liste von Endboard-Zeilen-Tupeln und ein `static`-Dictionary mit bekannten IDs.
+output: Ein `Counter` mit Präfix-Schlüsseln `unit:`, `item:`, `trait:` und `augment:`, das unbekannte IDs samt Häufigkeit führt.
+entscheidungen:
+- Filtert Unit-Drift um erwartbar unbekannte Beschwörungen/PvE-Einheiten anhand von Namenshinweisen heraus.
+  beleg: "if not any(h in api.lower() for h in BENIGN_UNIT_HINTS):"
+- Vereinigt Items und Augments zu einem einzigen `known_items`-Set, um Doppellookups zu vermeiden.
+  beleg: "known_items = set(static[\"items\"]) | set(static[\"augments\"])"
+- Zählt bei Items nur Drift, wenn das Item dem aktuellen Set oder dem generischen `TFT_Item_`-Schema angehört.
+  beleg: "if item.startswith(\"TFT_Item_\") or item.startswith(set_prefix):"
+kanten:
+- nutzt: backend/tft/matches/extract.py::BENIGN_UNIT_HINTS
+- wird-genutzt-von: backend/tft/matches/extract.py::extract_all
+
+## backend/tft/matches/extract.py::extract_all
+beschreibung: Liest alle noch nicht verarbeiteten Roh-Matches aus der Datenbank, extrahiert ihre Endboard-Zeilen, prüft sie gegen die statischen Daten und schreibt sie persistent in die `endboards`-Tabelle.
+input: Eine geöffnete DB-`connection` mit Schema `matches`/`endboards` und ein `static`-Dictionary mit bekannten IDs.
+output: Ein Tupel `(n, total_unknown)` mit Anzahl geschriebener Zeilen und aggregiertem Drift-Counter.
+entscheidungen:
+- Selektiert nur Matches, deren `match_id` noch nicht in `endboards` vorkommt, um Doppelverarbeitung zu vermeiden.
+  beleg: "SELECT raw FROM matches WHERE match_id NOT IN (SELECT DISTINCT match_id FROM endboards)"
+- Verwendet `INSERT OR IGNORE`, damit Wiederholungsläufe keine Duplikatfehler erzeugen.
+  beleg: "\"INSERT OR IGNORE INTO endboards VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\""
+- Sammelt Drift in einem einzigen Counter statt pro Match, damit das Endergebnis meldbar bleibt.
+  beleg: "total_unknown.update(validate_ids(rows, static))"
+kanten:
+- ruft-auf: backend/tft/matches/extract.py::extract_match
+- ruft-auf: backend/tft/matches/extract.py::validate_ids