233 lines
18 KiB
Markdown
233 lines
18 KiB
Markdown
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||
# 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](../desktop/almanac/DATA_CONTRACT.md).
|
||
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.
|