Files
Dreierpack-Manager/docs/new_ui/desktop/almanac/DATA_CONTRACT.md
T

16 KiB

Almanach · Datenvertrag der UI-Projektion

Stand: 24. Oktober 2026. Dieser Vertrag beschreibt die native Präsentationsschnittstelle des Almanachs. Er ist kein neues Engine-Speicherformat. Die gegenwärtige Quelle ist ein unveränderliches Pseudoarchiv; eine spätere Modern-Sessionprojektion kann denselben Lesevertrag bedienen.

Besitz und Lesezugriff

DataSource::read_almanac(const Json &request) const liefert eine JSON-Antwort. Nicht unterstützte Quellen antworten mit {"ok":false,"error":"almanac_unavailable"}. DemoSource leitet an query_demo_almanac(archive, request, state.date) weiter.

Das separat gehaltene Demoarchiv hat die Form {schema: "openbmh-ui-demo-almanac@1", matches: [...]}. Es liegt nicht in Snapshot.state oder UI-Demoständen. Abfragen geben eigenständige Ergebniskopien zurück und verändern weder Archiv noch Revision, Änderungsmarkierung, Geld oder RNG. Die App hält ihre Navigation nur in flüchtigen Feldern. Das Laden eines UI-Demostands ändert den Abfragestichtag, importiert aber kein Enginearchiv. Bestehende .obs- Dateien und F10-Daten werden von diesem Paket weder gelesen noch geändert.

Requests und Antworten

Requests sind Objekte mit genau den angegebenen Schlüsseln. Datumswerte sind gültige Gregorianische ISO-Daten YYYY-MM-DD; Jahre sind ganze Zahlen von 1 bis 9999. Boolesche Werte und Fließkommazahlen ersetzen keine Ganzzahlen. Der Stichtag as_of ist kein frei überschreibbarer Requestparameter: Die Datenquelle bindet ihn an das gespeicherte Datum.

Request Erfolgsantwort zusätzlich zu ok: true
{kind: "index"} years: [Jahre], match_count, first_date, last_date
{kind: "calendar", year: 2025} year, days: [{date, count, highlights: [Match-IDs]}]
{kind: "day", date: "2025-08-03"} date, matches: [vollständige Records]
{kind: "match", id: "demo:almanac:2025:0"} match: vollständiger Record

years ist aufsteigend und enthält nur Kalenderjahre sichtbarer Records. first_date und last_date sind bei leerem Archiv null, match_count ist dann 0. Ein Jahreskalender enthält nur Tage mit sichtbaren Partien, chronologisch geordnet. count zählt alle Partien des Tages. highlights enthält in der Demo die IDs von Partien mit Verlängerung, Elfmeterschießen oder mindestens vier Spieltoren insgesamt; es enthält keine zusätzlichen Ergebnisse. Die Tagesabfrage erhält bei Partien desselben Datums ihre ursprüngliche Archivreihenfolge.

Alle vier Abfragen filtern zuerst auf record.date <= as_of. Damit verraten weder die Jahresauswahl noch Anzahlen, Datumsgrenzen oder direkte Matchabfragen zukünftige Partien. Ein gültiger leerer Tag oder ein Jahr ohne sichtbare Daten liefert ein leeres Array. Unbekannte und noch nicht sichtbare Match-IDs liefern denselben Fehler.

Fehler haben die Form {ok: false, error: "..."}:

Fehler Bedeutung
almanac_unavailable Datenquelle unterstützt diese Projektion nicht.
invalid_almanac_request Ungültige Requestform, unbekannte Art, zusätzliche Felder oder ungültiger Wert.
invalid_almanac_cutoff Ungültiges Stichtagsdatum.
invalid_demo_almanac Das separat gehaltene Demoarchiv verletzt seinen Vertrag.
almanac_match_not_found Match-ID unbekannt oder jenseits des Stichtags.

Diese Fehlercodes beschreiben den nativen Provider. Der private HTML-Arbeitsstand besitzt eigene Fehlerbezeichnungen; sein normalisierter Recordaufbau und seine erfolgreichen Leseprojektionen folgen demselben fachlichen Vertrag.

Normalisierter Matchrecord

Alle folgenden Hauptfelder sind vorhanden. „Nullable“ bedeutet einen expliziten JSON-Wert null, keinen ersatzweise erfundenen Inhalt.

Feld Typ und Bedeutung
id Stabile, nicht leere Match-ID.
date ISO-Kalendertag des gespielten Matches.
season Historische Saisonbeschriftung, etwa 2025/26; kein Kalenderjahrfilter.
competition {id, name, type} mit historischen Werten; type beispielsweise league, cup oder friendly.
round Positive ganze Spieltags- oder Rundennummer.
home, away Je {id, name, crest, manager}; unterschiedliche stabile Vereins-IDs.
result Getrennte Ergebnisphasen gemäß folgendem Abschnitt.
referee Historischer Name oder null.
attendance Bekannte ganze Zuschauerzahl einschließlich 0, sonst null.
weather {temperature, rain}; beide ganzzahlig oder null, Regen im Bereich 0..7.
lineups {home, away}; jede Seite entweder null oder {starters: [...], bench: [...]}.
events Geordnetes Array der unten definierten Ereignisse.

crest ist ein GUI-/Katalog-Assetverweis oder null. Namen und Verweise werden als historische Snapshotwerte gehalten. Das DTO enthält keine historischen Bildbytes und belegt deshalb nicht, dass eine später unter demselben Assetverweis geladene Grafik dem früheren Wappenstand entspricht. Der aktuelle Bildresolver darf eine Referenz darstellen; daraus folgt keine zugesicherte historische Bildarchivierung.

manager ist entweder {id, name} für einen archivierten menschlichen Manager oder null für die in der Demo gesichert computergesteuerte Seite. Der Renderer zeigt dafür „Computer“. Ein künftiger Adapter darf einen ungültigen oder unbekannten menschlichen Managerverweis nicht stillschweigend auf diesen Computerfall abbilden.

Ein Aufstellungsspieler hat {id, name, position?}. position ist das einzige optionale Feld dieses Teilobjekts. In der Demo wird sie beim Archivaufbau aus dem Katalog kopiert, etwa gk, def, mid oder fwd. Die sichtbaren Kürzel TW, ABW, MIT und STU sind reine Darstellung. Der Renderer ersetzt fehlende historische Angaben nicht durch heutige Kaderdaten. Die Demo bildet bei ausreichendem Kader genau einen Torwart und zehn Feldspieler ab; alle übrigen Kaderspieler bleiben auf der Bank. Ist das nicht möglich, bleibt die betreffende Aufstellung null.

Die Laufnummer eines Aufstellungsplatzes ist kein Spieler-ID-Ersatz und keine historische Rückennummer. Historische Spieleridentitäten bleiben auch bei gleichnamigen Personen getrennt. Katalogumbenennungen nach dem Archivaufbau verändern weder Vereins- noch Spieler- oder Managernamen bereits erzeugter Records.

Ergebnisphasen

result enthält immer folgende Schlüssel:

Feld Bedeutung
regulation [Heimtore, Gasttore] nach regulärer Spielzeit oder null, falls unbekannt.
extra Ausschließlich zusätzlich in der Verlängerung gefallene Tore; bei nicht gespielter oder unbekannter Phase null.
penalties Separates Ergebnis des Elfmeterschießens; ohne Elfmeterschießen null.
final Spielendstand nach 90 beziehungsweise 120 Minuten, ohne Tore des Elfmeterschießens.
extra_played Explizit bekanntes boolesches Kennzeichen für gespielte Verlängerung.
penalties_played Boolesches Kennzeichen für gespieltes Elfmeterschießen.

Alle bekannten Ergebnisse sind Paare nicht negativer ganzer Zahlen. Sind reguläre Zeit und Verlängerung bekannt, gilt pro Seite regulation + extra == final. Beispiel:

{
  "regulation": [1, 1],
  "extra": [1, 1],
  "penalties": [4, 3],
  "final": [2, 2],
  "extra_played": true,
  "penalties_played": true
}

extra: [0, 0] bezeichnet eine bekannte torlose Verlängerung und ist etwas anderes als extra: null. Die aktuelle Demo erlaubt bei gespielter Verlängerung unbekannte Teilstände. Bei gesetztem penalties_played verlangt ihr Validator dagegen ein bekanntes, entscheidendes Elfmeterschießenergebnis. Das Elfmeterschießen wird niemals zum Spielendstand addiert. Ohne gespielte Verlängerung bleibt extra stets null.

Die booleschen Phasenkennzeichen sind in der Demo ausdrücklich bekannt. Für einen Liveadapter mit unbekannter ET-Teilnahme muss vor der Anbindung ein ausdrücklicher Unbekanntzustand vereinbart werden. false wäre dafür kein zulässiger Ersatz; aus decided == 2 einfach true abzuleiten wäre ebenfalls unbelegt.

Ereignisse

Jedes Ereignis enthält genau {kind, minute, side, player, other, detail}. side ist home oder away. player und other sind jeweils {id, name} oder null; sie tragen keine nachträglich aus dem Kader ergänzten Werte.

kind Bedeutung von Spieler und Zusatzangaben
goal Torschütze, ggf. Vorlagengeber unter other; detail bezeichnet die Torart.
miss Schütze, ggf. Zuspieler unter other; gleiche Detailarten wie beim Tor.
yellow Verwarnter Spieler.
second_yellow Spieler mit Gelb-Rot.
red Spieler mit direkter Roter Karte.
injury Verletzter Spieler.
substitution player kommt ein, other geht aus; unbekannte Beteiligte bleiben null.
shootout Schütze eines einzelnen Versuchs; detail: 1 getroffen, detail: 0 verfehlt.

Bei Tor und Fehlschuss bedeutet detail: 0 Spiel, 1 Elfmeter/Freistoß, 2 Nachschuss und 3 Ecke. Die gemeinsame Kategorie Elfmeter/Freistoß wird nicht willkürlich in zwei Ursprünge aufgeteilt. Die übrigen Ereignisarten verwenden in der Demo detail: 0.

Spielereignisse tragen Minuten ab 1, in der Verlängerung bis 120. Shootout-Ereignisse verwenden symbolisch Minute 121. Die ursprüngliche Arrayfolge ist bei gleicher Minute maßgeblich; insbesondere dürfen Shootoutversuche nicht nach Spieler, Seite oder Trefferstatus umsortiert werden. Die Anzeige sortiert Minuten stabil und nummeriert alle Versuche einschließlich Fehlversuchen fortlaufend.

Null, Nullwert und Validierung

0 ist ein bekannter Wert, etwa keine Zuschauer, null Grad oder kein Regen. null bedeutet fehlende Information. Leere Aufstellung, fehlender Spieler und Computersteuerung dürfen nicht über numerische Null oder den ersten Eintrag einer Tabelle erraten werden. Fehlende Namen und Metadaten erscheinen neutral; ein fehlender Kader erhält keine erfundene Startelf.

valid_demo_almanac() prüft den vollständigen Demoaufbau, eindeutige Match-IDs, Ergebnis- und Ereigniskonsistenz, gültige Referenzen innerhalb bekannter Aufstellungen, genau eine bekannte Torwartposition bei vollständig bekannten Startpositionen, Wechsel, Platzverweise und die Vollständigkeit eines entscheidenden Shootouts. Die Demoereignisse sind vollständig und stimmen mit den Spieltoren überein. Dieser Validator ist kein Ersatz für einen künftigen Adapter mit ausdrücklich unvollständigen Engineaufzeichnungen; dort dürfen fehlende Phasen nicht durch erfundene Ereignisse passend gemacht werden.

Spätere Modern-Sessionprojektion und F10

Grundlage bleiben almanach.md und almanac.hpp. F10 enthält bereits historische Saison-, Vereins-, Spieler-, Manager- und Schiedsrichtertabellen, Aufstellungen, Zuschauer, Wetter und acht Ereignisarten. Die Phasenlücke beim Ergebnis bedeutet nicht, dass F10 insgesamt nur einen Endstand und ein Ereignisprotokoll speichern würde.

Der spätere Adapter gehört an die konstante Leseseite der Modern-Session. Er soll nur benötigte Saisons bei Bedarf dekodieren und historische Tabellen in UI-Records auflösen. Renderer und Navigation bleiben unabhängig von OBS, Binärdekodierung und laufenden Engineobjekten. Abgeschlossene Archive müssen dafür nicht in jeden GUI-Snapshot kopiert werden. Dieses Paket implementiert oder verändert diesen Adapter nicht.

Die fachliche Zuordnung für den späteren Adapter ist:

Engine-/F10-Quelle Normalisiertes UI-Feld
Saisonkopf und ursprünglicher Matchordinal Stabile id und Saisonbeschriftung season.
date, display_start_year, almanac_date() ISO-Kalendertag date; daraus Kalenderjahr und Cutoff.
type, league, stage, round sowie verfügbare Wettbewerbsmetadaten competition und round; Ligakennung und Pokalstufe sind keine austauschbaren Indizes.
Saison-Clubtabelle und home/away Historische Vereins-IDs und Namen unter home/away; Bildreferenzen sind keine historischen F10-Bildbytes.
home_manager/away_manager und Managertabelle Historische menschliche Manager; gesichert -1 bezeichnet Computer.
home_goals/away_goals result.final, ohne Shootouttore.
home_shootout/away_shootout, decided Separates result.penalties und bekannte Entscheidungsart; keine pauschale ET-Ableitung.
Vollständige Torereignisse und gesicherte Phaseninformation Soweit belegt result.regulation und zusätzliche Tore unter result.extra.
Schiedsrichterreferenz, Zuschauer, Temperatur und Regen referee, attendance, weather, nach Referenz- und Bekanntheitsprüfung.
Aufstellungsvektor und saisonale Spielertabelle Historische Spieleridentitäten und Namen; starters/bench nur bei belegbarer Trennung.
AlmanacEvent und seine historischen Spielerreferenzen Die acht events.kind-Werte, Minute, Seite, Spieler, zweiter Spieler und Detail.

Die konkrete Gap-Liste für diese spätere Integration lautet:

  1. Ergebnisphasen: AlmanacMatch.home_goals/away_goals enthalten den Spielendstand ohne Shootout; separate Shootouttore sind vorhanden. Ein eigener 90-Minuten-Stand und ein ausdrückliches ET-Kennzeichen fehlen im Fall decided == 2. Reguläre Tore und zusätzliche Verlängerungstore dürfen nur bei gesichert vollständigen Daten aus Torereignissen und Endstand abgeleitet werden. Fehlen solche Daten, bleiben Teilstände unbekannt. Aus Shootout oder decided == 2 allein darf niemals pauschal auf eine gespielte Verlängerung geschlossen werden.
  2. Matchidentität: Ein eigenes stabiles Match-ID-Feld fehlt. Saisonkennung plus ursprünglicher Matchordinal kann den stabilen Projektionsschlüssel bilden. Eine aktuelle Sortier- oder Zeilennummer reicht nicht. Die Demo verwendet entsprechend demo:almanac:<Saisonstartjahr>:<ursprünglicher Ordinal>.
  3. Historische Namensstände: Die Tabellen werden pro Saison geführt. Vereine und Spieler werden beim ersten Eintrag ihrer stabilen ID aufgenommen; Namen werden nicht für jeden einzelnen Matchtag erneut eingefroren. Diese historischen Tabellen sind maßgeblich und dürfen nicht durch heutige Kadernamen ersetzt werden.
  4. Spielerattribute: F10-Spieler enthalten ID, Vorname, Nachname und Nation, keine archivierte Rückennummer, Position oder Stärke. Optionale Demo-Positionen stammen aus dem POC-Aufbau und sind keine vorgeblich aus F10 gelesenen Daten.
  5. Startelf und Bank: Der Enginevektor bedeutet nominell elf Starter, anschließend Bank. Der Recorder überspringt jedoch leere Plätze. Bei unvollständiger Startelf mit Bank kann die Grenze im Vektor allein mehrdeutig sein. Kader von Länder- und Amateurteams fehlen ausdrücklich. Die UI darf aus dieser Unsicherheit keine erfundene Elf konstruieren; das normalisierte DTO trennt beide Bereiche ausdrücklich.
  6. Ereignisbedeutung: Goal.detail == 1 kombiniert Elfmeter/Freistoß; 0, 2, 3 stehen für Spiel, Nachschuss und Ecke. Substitution.player bezeichnet Ein, other Aus. kAlmanacNone == 0xffff ist ein fehlender Verweis, kein Spieler an Tabellenposition 0.
  7. Shootoutfolge: Mehrere Versuche teilen typischerweise Minute 121. Ihre ursprüngliche Arrayreihenfolge muss erhalten bleiben; jeder Treffer und Fehlversuch zählt. Ein gesondertes Zeit- oder Sequenzfeld für diese Kicks existiert nicht.
  8. Fehlende Rohwerte: Manche Raw-Standardwerte unterscheiden eine fehlende Angabe nicht von einer gültigen Null, etwa bei Zuschauern, Temperatur und Regen. Der Adapter braucht gesichert bekannte Werte oder null, keine Heuristik „0 bedeutet unbekannt“. Schiedsrichterindex 0 bezeichnet keinen ausgewählten Schiedsrichter.
  9. Referenzgrenzen: Die Binärdekodierung prüft nicht jeden Spieler-, Manager- oder Schiedsrichterindex. Der Adapter muss Grenzen prüfen und unbekannte Referenzen neutral behandeln. Ein ungültiger menschlicher Managerindex darf nicht unbemerkt als Computersteuerung erscheinen.
  10. Datumdomäne: Datum ist aus Tageszähler und display_start_year über almanac_date() zu übertragen. Ein Saisonstartjahr ist kein Kalenderjahrfilter. Engine- und Schreibtischdatum müssen deshalb ausdrücklich in die Kalenderdatumdomäne der UI übersetzt werden.

Die Wappenfrage bleibt daneben eine gesonderte Darstellungsgrenze: Assetreferenzen sind vorhanden, historische Bildbytes sind durch den vorliegenden Vertrag nicht belegt. Weder Namen noch Positions- oder Bildlücken rechtfertigen einen stillen Zugriff des Renderers auf heutige Spielwerte oder einen behaupteten vollständigen historischen Bildstand.