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

233 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!-- 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.