300 lines
16 KiB
Markdown
300 lines
16 KiB
Markdown
# Almanach · Datenvertrag der UI-Projektion
|
|
|
|
Stand: 24. Oktober 2026. Dieser Vertrag beschreibt die native
|
|
Präsentationsschnittstelle des [Almanachs](README.md). 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:
|
|
|
|
```json
|
|
{
|
|
"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](../../../new_engine/almanach.md) und
|
|
[almanac.hpp](../../../../src/modern/game/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.
|