Files
Dreierpack-Manager/docs/new_ui/integration/ALMANAC.md
T

18 KiB
Raw Blame History

Almanach: belastbare Auswertungen statt erfundener Statistik

Grundlage sind src/modern/game/almanac.hpp/.cpp, src/modern/content/statistics.cpp, die vorhandenen Engine-Notizen und der bereits vereinbarte Almanach-Lesevertrag. Dieses Dokument erweitert die Anforderungen auf alle Statistikmenüs. Es ändert weder F10/OBS noch Classic oder die Saisonlogik. Die folgenden Normalformen und Regeln sind als Entwurf zu entscheiden; bestehende Rohdaten werden nicht als vollständiger bezeichnet, als sie tatsächlich sind.

Vorhandene Aufzeichnungen und ihre Grenzen

F10 führt historische Saison-, Liga-, Vereins-, Spieler-, Manager- und Schiedsrichtertabellen sowie Spiele, Ereignisse, Aufstellungen, Endtabellen und Sieger. Geschlossene Saisons bleiben selbständig lesbar. Spieleridentitäten wechseln bei Wiederverwendung eines Laufzeitslots; ein generierter neuer Spieler ist eine neue Karriere, auch wenn der Name gleich bleibt. Auf-/Abstieg tauscht Laufzeitnummern, nicht die Weltidentität eines Vereins.

Die tatsächlich vorhandenen Ereignisse sind Tor, Gelb, direkt Rot, Gelb-Rot, Verletzung, Wechsel, Shootoutkick und Fehlschuss. Weitere DTO-Kategorien wie Eigentor, Keeperparade, VAR oder administrativer Stand sind Erweiterungshaken, keine Behauptung eines bereits vorhandenen F10-Feldes. Goal.detail==1 fasst Elfmeter/Freistoß zusammen. Daraus darf die UI keine getrennten Zähler erfinden. Miss belegt eine Chance ohne Tor; es belegt nicht sämtliche Schüsse, Schüsse aufs Tor oder Torwartaktionen.

Nicht jede Nation, jeder Amateur oder Pokalausländer hat einen Kader. Der Recorder überspringt leere Kaderplätze; deshalb ist die Grenze „erste elf = Startelf“ in einem verkürzten Vektor nicht immer gesichert. F10 speichert keine historischen Rückennummern, Positionen, Ratings, Verletzungsdiagnosen, Gehälter, Transferpreise, Ballbesitz, xG oder Laufdistanzen. Saisonale Namen sind der historische Tabelleneintrag dieser ID, nicht zwingend ihr tagesgenauer Namensstand.

AlmanacStanding verwendet unter anderem begrenzte Tor-/Spielzähler. Neue Projektionen summieren in ausreichend breiten Zählern und benennen vorhandene Formatgrenzen; sie erzeugen keine Genauigkeit, die im Archiv verlorenging. Frühere Binärversionen ohne Tabellen/Sieger haben bei solchen Auswertungen eine Datenlücke, nicht automatisch null Titel.

Mindestidentitäten und Kontext pro Match

Bedarf Normalisierung / notwendiger Nachweis
Karriere und Saison careerId, stabile seasonId, Start-/Enddatum, display_start_year, Archivversion und Archivdigest
Fixture und Austragung dauerhafte fixtureId für die geplante Partie; matchId für die tatsächlich gewertete Austragung; Replay/Verschiebung explizit verknüpfen
Ältere Matches ohne IDs persistierter Schlüssel aus Karriere, Saison und ursprünglichem Matchordinal; nicht aus aktueller Sortierung, Vereinsnamen oder Datum konstruieren
Wettbewerb stabile Competition-ID, Edition-ID, Saison, Liga/Pokal/National/Freundschaft/Indoor/Relegation, Gruppe/Stufe/Runde, Hin-/Rückspielbezug
Format outdoor/indoor, tatsächliche Perioden, Kaderlimit, tatsächliche Personen auf dem Feld, Wechselregelreferenz; Indoor nicht als Outdoor mit anderem Hintergrund
Beteiligte beide historischen Team-IDs; Club/National unterscheiden; Manager-ID und zum Zeitpunkt gültige Amtszeit/Steuerungsart je Seite
Zeit und Reihenfolge ursprüngliche Ereignisreihenfolge, Periode, Minute, bekannte Sekunden/Nachspielzeit; ISO-Spieltag getrennt vom Saisonlabel
Ergebnis Spieltore ohne Shootout, getrennte PSO-Tore, Entscheidungsart, ET-Teilnahme, bekannte 90-Minuten-/ET-Teilstände, Abbruch/Wertung/Annullierung
Aufstellungen Starter und Bank getrennt, sichere Klassifizierung, nominierter Kader, Feldzahl und Abwesenheiten; fehlende Spielerreferenz = null
Umgebung Schiedsrichter-ID falls belegt, sonst historischer Name/Unbekannt; Zuschauer, Kapazität, Wetter; echte Null erhalten
Vollständigkeit Coverage für Ereignisse, Akteure, Perioden, Aufstellungen, Disziplin, Wetter, Zuschauer und Shootoutfolge
Zählkontext Regel-ID/Version, zählen für Tabelle/Spielerstatistik/Serien/Highscore, Freundschafts-/Indoorbehandlung, effektiver Korrekturstand

F10 besitzt bislang keine eigenen dauerhaften Match-/Event-IDs. Ein stabiler Adapter-ID-Index kann vorhandene Saisonordinale abbilden, ohne Archive umzuschreiben. Neue Aufzeichnungen sollten Fixture-/Match-/Event-IDs originär erhalten. Ereignis-IDs dürfen sich bei Pagination, Übersetzung, Sortieren oder Korrekturen nicht ändern. Die ursprüngliche Reihenfolge ist besonders für gleichminütige Shootoutkicks und Verletzung → Wechsel unverzichtbar.

Ergebnisphasen und ET/PSO

result.final enthält Tore aus dem Spiel einschließlich belegter Verlängerung, ohne Shootout. regulation enthält die regulären Tore; extra im Entwurf nur die zusätzlich in ET erzielten Tore. Bei vollständig bekannten Phasen gilt final = regulation + extra. Ein Shootout entscheidet den Sieger, erhöht aber weder Spieltore noch Ligatore, Tordifferenz, Torschützen- oder Vorlagenzähler.

Für bestehendes decided==2 ist ET-Teilnahme allein nicht gesichert. Ohne weitere Information sind extraTimePlayed, regulation und extra deshalb null. Ein Match kann direkt ins Shootout gehen. Die UI darf keine 120′ und keinen bekannten Halbzeitstand aus einem bloßen PSO-Endstand anzeigen. Auch minute 121 ist ein altes Markerformat, keine sekundengenaue Dauer.

Nur wenn Vollständigkeit und Phasen nachgewiesen sind, darf ein Projektor Teilstände aus Torereignissen ableiten und gegen den Endstand prüfen. Bei einer Lücke wird nicht mit Phantomtoren aufgefüllt. Eine administrative Wertung kann absichtlich vom Torprotokoll abweichen und benötigt ihren eigenen Kontext.

Korrektur-, Dedupe- und Aggregationsmodell

Vorschlag für neue Projektionen:

  1. Originalarchive bleiben unverändert. Ein append-only Korrekturledger verweist auf Archivdigest, Match-/Event-ID, Grund, Erfassungs- und Wirksamkeitsdatum.
  2. replace, void, restore bilden einen expliziten Versionsverlauf. supersedesId darf keinen Zyklus erzeugen; konkurrierende Korrekturen brauchen eine definierte Konfliktentscheidung. Kein „letzter Arrayeintrag gewinnt“.
  3. Ein Match/Event ist je Snapshot genau einmal effektiv. Replays haben eine eigene Austragungs-ID; die Annullierung der alten Austragung ist explizit.
  4. Reads binden asOf, Filter, Regelversion und projectionRevision an einen konsistenten Stand. Rückdatierte Korrekturen invalidieren betroffene Statistiken/Cursor und erzeugen eine neue Projektionsrevision.
  5. UI-Rückblick, Tickerreplay und ein erneut zugestelltes Event buchen nichts. Live zählt dieselbe Event-ID/Revision nicht doppelt; ein höherer Eventstand ersetzt seine ältere Projektion statt sie nochmals hinzuzufügen.
  6. Finanzkorrekturen sind Gegenbuchungen über reversalOf/Transaktions-ID; Matchkorrekturen erzeugen keine ausgedachten Einnahmenrückzahlungen.

Das Korrekturledger ist eine Anforderung. Es existiert dadurch noch kein historischer Engine-Editor. Rechte, Konfliktlösung und Archivmigrationsgrenze stehen in D06. Beispiele almanac-correction.json und die bounded QA prüfen nur die vorgeschlagene Identitäts-/Revisionsform.

Auswertungen: Quelle, Aggregation und offene Fragen

Ansicht Aus F10 ableitbar, soweit vollständig Zusätzlich nötig / bewusst nicht ableitbar
Tore zählbare Goal-Events je Player-ID/Competition-Edition/Saison; Shootout separat Eigentor- und administrativer Trefferkontext; fehlende Akteure als unbekannte Teamtore, nicht fremdem Spieler zuordnen
Vorlagen gültiges Goal.other, je Tor höchstens eine belegte Vorlage kein Erfinden aus Nachschuss/Freistoß; Assistregel und Eigentorbehandlung versionieren
Gelb/Rot YellowCard, SecondYellow und RedCard getrennt zählen ob zweite Gelbe in „Gelb“ nochmals erscheint und wie Gelb-Rot in Fairplay gewichtet wird, entscheiden
Einsätze Menge der belegten Starter ∪ eingewechselten Spieler je Match verkürzte unklassifizierte Aufstellung; Indoor-Wiederkehr; Bank ohne Einsatz zählt nicht
Minuten bekannte Intervalle auf dem Feld minus Ausschluss/Abgang Sekunden-/Nachspielzeit-/Halbzeitgrenzen und Indoor-Wechselpaare; bei Minutenpräzision keine exakten Sekunden vortäuschen
Fairplay Karten pro tatsächlich handelndem Team; danach Strafpunktregel Regel-ID, zweite Gelbe, Strafen außerhalb des Matchs, Wettbewerbsfilter und stabile Gleichstände
Erfolge/Vereinsgeschichte Meister/Endplatz und gespeicherte Sieger pro Edition Teilnahme/Nichtteilnahme, ausgeschiedene Runde, Auf-/Abstiegskontext und Amtszeiten; Siegerliste allein reicht nicht
Highscore einzelne Titel/Plätze können beitragen autoritative Highscoreprojektion/Regelversion, Vermögen, Einrichtungen, Teamwert, Geduld, Managerhistorie und externer Ranglistenbestand
Möglichkeiten belegte Goals/Miss als benannte Engine-Chancenarten kein vollständiger Schussdatensatz, keine xG/Paraden/„aufs Tor“-Quote ohne zusätzliche Enginezählung
Transferhistorie nichts Belastbares über Geschäftsvorgänge Transferledger mit Parteien, Personen-ID, Vertrag, Gebühr, Leihart, Abschluss/Wirksamkeit/Storno, Währung
Analytics Tor-/Punkt-/Ergebnisserien aus belegten Matches Stärke/Moral/Finanzen/Publikumsentwicklung brauchen datierte Snapshots/Ledger; REL.-Basis 0 ist undefiniert
Ewige Tabelle zählbare Ligamatches, Endtabellen und historische Teamidentitäten Regel-/Punkteabzugs-/Wertungsledger, Saisonteilnahme und Tabellen-Tiebreakversion
WM-/Nationalstatistik nationale Wettbewerbseditionen, Spiele/Sieger, bekannte Spielerereignisse Qualifikation/Gruppentabellen/Bracket/Turnierregeln, Nominierungen, Teams ohne Kader und historische Nationalitätszuordnung
Saisonfinanzen Zuschauerzahlen allein Finanzledger mit Kategorie, periodischer Abgrenzung, Brutto/Netto, Prämien, Gehältern, Zinsen, Krediten und Storno; Einnahmen nie als Zuschauer × heutigen Preis raten
Serien/Rekorde chronologische Spielausgänge und Torfolgen je definierter Auswahl Umgang mit PSO, neutralem Platz, abgesagten/abgebrochenen/wiederholten Spielen, Wettbewerbs-/Saisongrenzen; Leistungs-/Finanzrekorde brauchen Zusatzdaten
Siegerlisten winners, Liga-Endtabellen und Editionen Archivversionen ohne Sieger, Duplikatprüfung Finale/Meister, Hallen-Turniere vs Masters, geteilte Titel/kein Zweiter
Minutenstatistik vollständig zugeordnete Ereignisse in benannten Zeitintervallen Zeitbasis für ET/Indoor/Nachspielzeit, genaue Eventarten; unbekannte Periode hat eigene Unknown-Gruppe
Direkter Vergleich Begegnungen zwischen stabilen Team-IDs, je Contextfilter Heim-/Gast/neutral, PSO-/ET-Wertung, Vereinsumbenennung; Namen sind keine Identität
Zuschauer/Schiedsrichter/Wetter vorhandene Matchfelder mit sicherer Bekanntheit Kapazität am Matchtag, neutraler Ort, Schiedsrichter-Person-ID, fehlende vs tatsächliche Nullwerte
Sportschau/Elf des Tages Matchereignisse können Fakten belegen autoritative Ratings/Auswahlregel und Repräsentation fehlender Kader. Kein HTML-Stärke-plus-Bonus-Algorithmus

Spieler- und Kartenzähler

Die vorhandene Engine-JSON-Abfrage player_stats zählt YellowCard, SecondYellow, RedCard getrennt; Sortierung „red“ benutzt direkt Rot plus Gelb-Rot. Sortiergleichstand: weniger Einsätze, danach Name; gleicher Metrikwert erhält denselben Wettbewerbsrang. Der ausgegebene Verein ist die Seite des letzten Spiels in dieser Auswahl, nicht notwendigerweise der aktuelle Arbeitgeber. Die neue Projektion sollte das als lastRepresentedTeam kennzeichnen und mehrere historische Teams nicht verschlucken.

Konkrete Adapterprüfung: Die vorhandene Implementierung nimmt bei Einsätzen min(11,lineup.size()) als Starter und erhöht bei jedem Substitutionsevent. Das beweist keine korrekte individuelle Einsatzzahl bei verkürzten Aufstellungen, sechs Indoor-Feldspielern oder Wieder-Einwechslungen. Neue Reads müssen diese Kontexte testen beziehungsweise partial melden. Das ist ein Vertragsrisiko, kein hier nachgewiesener Spielsimulationsfehler und keine still korrigierte Regel.

Vorgeschlagener Einsatznachweis: pro Match Player-ID als Menge erfassen; ein bekannter Einsatz zählt genau einmal, auch bei zweimaligem Betreten. Für spezielle Indoor-Rotationsregeln ist zu klären, ob die bisherige Anzeige bewusst eine andere Größe meint. Einsätze und Minuten bleiben getrennte Metriken.

Die Fairplay-Goldformel ist Gelb + 4 × Rot. Sie entscheidet nicht, ob „Rot“ Gelb-Rot einschließt und ob die erste/zweite Gelbe doppelt zählt. Bis D08 geklärt ist, bleiben yellow, secondYellow, straightRed, dismissals eigenständige Metriken; fairplayPoints ist entweder autoritativ mit Regel-ID oder unbekannt. Keine UI berechnet sich ihre eigene alternative Tabelle.

Titel, Erfolge und Managerwechsel

Meister wird je Competition-Edition einmal aus der maßgeblichen Abschlusstabelle oder einem referenzierten Winner-Record erkannt, nicht aus beiden doppelt. Pokal-/Indoor-Ausgaben innerhalb einer Saison benötigen Editionen. Masters und vorgelagerte Hallenturniere sind unterschiedliche Titel. Nichtteilnahme ist ein expliziter Teilnahmezustand, kein früher Pokalausgang und kein letzter Platz.

Managererfolge zählen nur zur belegten Amtszeit/Steuerung. Aufgeben löscht weder die historische Manager-ID noch frühere Titel. Die neue KI übernimmt das Team, nicht den Namen, die Person oder deren Highscorehistorie. Eine Quelle mit nur Managername/Slot pro Match kann gleiche Namen oder Slotwiederverwendung nicht zuverlässig trennen; erforderlich ist ein persistierter ID-/Amtszeitenindex. Bundestrainerübernahme/Rückkehr kann eine andere aktive Rolle derselben Person sein; das ist nicht automatisch ein neuer Manager. Siehe D12/D13.

modern/game/highscore.cpp enthält bereits eine eigene autoritative Berechnung mit Kontexten für aktiven Manager/Saisonwechsel und Nationalrolle. Sie verwendet neben Titeln/Historie auch Nicht-Matchwerte. Der neue JSON-Adapter soll deren Ergebnis und Regel-/Kontextkennung transportieren; dieses Dokument übernimmt keine Konstanten als neue Regel und die UI darf die Berechnung nicht ersetzen.

Tabellen, Serien und Minuten

Tabellenpunkte hängen vom gültigen Regelprofil und Abzügen ab. Die 3/1/0- HTML-Demoregel ist kein universeller Ersatz. pointAdjustment kommt aus einem expliziten Nachweis; ein Unterschied zwischen Spielsumme und Endtabelle darf nicht willkürlich als Abzug „erklärt“ werden. Finale Tabellen sind für den historischen Endstand maßgeblich, Matches für nachgewiesene Teilzeiträume.

Serien werden je stabiler Team-ID, zählbarem Match und dokumentierter Wettbewerbs-/Saisonauswahl in tatsächlicher Austragungsreihenfolge gebildet. Ein Ligaremís mit späterem PSO-Sieg im Pokal ist nicht automatisch ein identischer Siegtyp. Rescheduled Fixtures behalten ihren ursprünglichen Spieltag und erhalten ein neues Austragungsdatum. Ein Wiederholungsspiel ist keine zweite Wertung der annullierten Austragung. Rekorde benötigen mehrere Gleichstandsinhaber.

Bei Minutenbuckets müssen Grenzen exakt angegeben sein, beispielsweise (0,5], (5,10] innerhalb einer belegten Periode. 45+2, 90+3, ET-Perioden und Indoor werden nicht still in den letzten 90-Minuten-Bucket geworfen. F10 liefert diese feine Periodengenauigkeit nicht immer; dann Unknown-Gruppe statt falscher Kurve. Es gibt keine Division durch unbekannte Spieldauer und kein REL.-Diagramm bei Basis 0 ohne ausdrücklichen Unavailable-Zustand.

Unverzichtbare Zusatzledger

Ledger / Snapshot Mindestfelder
Finanzbuchung ID, Transaktions-ID, Owner/Team, Konto/Kategorie, Buchungs- und Wirksamkeitsdatum, Betrag/Währung/Minor Units, Gegenpartei, Fixture-/Vertragsbezug, reversalOf
Transfer/Vertrag Personen-ID, abgebender/aufnehmender Club, Kauf/Leihe/Rückkehr, Offer-/Quote-ID, Statusverlauf, vereinbarte/gebuchte Beträge, Gehaltsperiode/Laufzeit, Abschluss-/Wirksamkeitsdatum, Storno
Manageramt unveränderliche Personen-ID, Slot nur als Präsentationsbezug, Team/Rolle, Start/Ende/Grund, aktive oder suspendierte Kontrolle, KI-Übergabe, Nationalübernahme/Rückkehr
Wettbewerbsregeln/Teilnahme Edition/Gruppe/Runde, Teilnehmer, Fortschritt/Ausscheiden, Punkte-/Tie-/PSO-Regelversion, Zählbarkeit für jede Auswertung
Teamzustand im Zeitverlauf datierte tatsächliche Stärke, Moral, Anlagen, Kapazität und Preise für historische Kurven/Highscore; nicht heutige Werte rückprojizieren
Nominierung Nationalteam, Datum/Edition, nominierte IDs, Heimatclub und bekannte Position zum Zeitpunkt, Grund für leeren/teilweisen Kader
Korrekturen/Wertungen Ziel-IDs/Digests, Operation, Version, wirksam/erfasst, Grund, Supersession, betroffene Aggregationen
Highscorebestand Ergebnis-ID, Manageridentität, Regel-/Kontextversion, Snapshotzeitpunkt, Komponenten und externer Persistenz-/Importkontext

Für alle Ledger gilt: keine UI-seitige Buchung während eines Reads, keine Präsentationsdaten als zweite Wahrheit und keine nachträgliche Vermischung von heutiger Kaderzuordnung mit historischen National-/Clubauftritten.

Kosten und Lesegrenze

Der Almanach kann über viele Saisons wachsen. Eine Abfrage dekodiert/cacht nur benötigte Saisons und aggregiert auf Engine-/Sessionsseite. Sie liefert Cursor, Gesamtzahl oder null, Filter, Sortierung, Coverage und Projektionsrevision. Die UI erhält weder alle Binärarchive in jedem Snapshot noch rohe Tabellen- Indizes. Cacheinvalidierung folgt Korrekturen/Regelversionen; geschlossene Archive werden durch bloßes Öffnen nicht neu geschrieben. Grenzen für Zeitraum, Abbruch langer Abfragen und cache budget sind unter D18 festzulegen.