228 lines
15 KiB
Markdown
228 lines
15 KiB
Markdown
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||
# Engine–Modern-UI: JSON-Datenvertrag für Desktop, Live und Nachspiel
|
||
|
||
**Arbeitsentwurf der Nacht 26./27. Oktober 2026, keine Fertigmeldung.** Dieses Paket benennt,
|
||
was die Oberfläche benötigt, welche Quellen bereits belegt sind und welche
|
||
Adapter beziehungsweise Engineentscheidungen noch fehlen. Es implementiert
|
||
weder Saisonregeln noch einen Engineadapter oder eine neue Matchoberfläche.
|
||
Alle Beispiele sind synthetisch. Sie dürfen nicht als gespielte Engineergebnisse,
|
||
als HTML-Referenzwerte oder als Regression gegen Originaldaten ausgegeben werden.
|
||
|
||
| Einstieg | Inhalt |
|
||
| --- | --- |
|
||
| [Kurzübergabe für Claude](MVP_FOR_CLAUDE.md) | Schlanker Einstieg und Lieferreihenfolge für die erste echte Anbindung |
|
||
| [Schemas](schemas/ui-contract.schema.json) | JSON Schema 2020-12; gemeinsame Typen, Readmodels, Kommandos, Fehler und Ergebnisse |
|
||
| [Index](schemas/contract-index.json) | Namen der vorgeschlagenen Reads und Commands |
|
||
| [Menüvertrag](menu-contracts.json) | 47 Menü-/Auswertungsbereiche mit sichtbaren Daten und Code-/HTML-Quellen |
|
||
| [Almanach und Auswertungen](ALMANAC.md) | Ereignisse, Identitäten, Vollständigkeit, Korrekturen, Aggregationen und notwendige Zusatzledger |
|
||
| [Pressevertrag](PRESS.md) | Semantische Events, unveränderliche DE/EN-Snapshots und Lösch-Dedupe |
|
||
| [Offene Entscheidungen](OPEN_DECISIONS.md) | Priorisierte Rückfragen für Claude/Engine, ohne stillschweigende Antworten |
|
||
| [Beispiele](examples/index.json) | 53 Dateien: vier Manager, Verein/National, ET, PSO, Indoor, unbekannte Altphasen, Geschäftsdaten und Aufgeben |
|
||
| [Quellbasis](provenance.json) | Getrennte Revisionen und Hashes der geprüften Vertragsquellen |
|
||
| [QA](QA.md) | Tatsächlich ausgeführte Schema-/Semantikprüfungen und Grenzen |
|
||
|
||
## Zwei öffentliche Grundlagen und eine private Referenz
|
||
|
||
Die untersuchte Modern-UI-/Enginebasis ist `origin/0.3` bei
|
||
`a207b0129e06f0659a5e7b30afa3680739a33029`. Das im selben Repository geprüfte
|
||
`origin/main` zeigt auf `b879d5be008739f69afef562fb4bce56f1bdc778` und enthält
|
||
**keine** `src/modern`- oder `docs/new_engine`-Dateien. Daraus folgt keine Aussage
|
||
über einen möglicherweise getrennten, neueren Claude-Enginezweig; dessen
|
||
Repository und Revision sind noch abzugleichen. Änderungen an diesen Grundlagen
|
||
müssen vor der Implementierung erneut verglichen werden.
|
||
|
||
Die private HTML-Referenz hat den separat protokollierten Git-Stand
|
||
zunächst `f8932de2009137e738962763c5fcbb75c2467570`; der abschließende
|
||
Hashabgleich protokolliert `72ddff945f75276d1b0a93e7a9cb5a61beefa9dd` plus
|
||
die parallel entstandenen Working-Tree-Änderungen. `match-model.js`,
|
||
`match-broadcast.js`, `match-intervention.js`, `post-match.js` und die Desktop-
|
||
Menüprovider wurden für Daten und Interaktionen gelesen. Zusätzliche uncommittete Änderungen sind unter `workingTreeChanges`
|
||
und mit ihren tatsächlichen Dateihashes protokolliert. Die JS-Dateihashes
|
||
sind ein Inventar, keine Behauptung einer vollständigen Browser- oder Bild-QA.
|
||
Öffentlich werden weder Originalgrafiken noch Originaltextinventare oder echte
|
||
Namen/Spieldaten mitgeliefert. Neue Manager-Aufgeben-Anforderungen stammen aus
|
||
dem Nutzerauftrag; ihre Auflistung behauptet noch keinen HTML-/Enginecode.
|
||
|
||
## Was heute vorhanden ist
|
||
|
||
`ModernSession::read()` und `read_statistics()` liefern bereits JSON für
|
||
`status`, `leagues`, `table`, `fixtures`, `squad`, `toto`, `sponsor`,
|
||
`competitions`, `winners` und `player_stats`. Diese Antworten sind **nicht**
|
||
bereits das hier vorgeschlagene `bmh-modern-ui@draft1`-Protokoll: durchgängiger
|
||
Umschlag, Manager-/Sessionidentitäten, Scope, Pagination und Revision fehlen
|
||
teilweise. Zudem benutzt die Leseseite bisher den aktiven Manager der Engine.
|
||
|
||
Daneben existieren zahlreiche C++-Projektionen und revisionierte Dienste für
|
||
Desktop, Transfers, Bank, Verträge, Trainingslager und Liveeingriffe. Ihre
|
||
Existenz ist in `menu-contracts.json` belegt. Ein C++-Request mit Laufzeitindizes,
|
||
Callbacks oder Quelladressfeldern ist noch kein stabiler JSON-DTO-Vertrag.
|
||
Der Adapter muss solche internen Bezüge in IDs und semantische Aktionen
|
||
übersetzen. Keine UI greift direkt auf `GameState`, Archive oder RNG zu.
|
||
|
||
Die aktuelle native Modern UI verwendet für viele Menüs weiterhin `DemoSource`
|
||
und deterministische Vorschauen. Der während der Nacht ergänzte `live-ticker-adapter.js` ist eine getrennte
|
||
HTML-Demoadaption; seine aus Portraits gebildeten Manager-IDs und Zeit/ID-
|
||
Sortierung sind kein Enginevertrag. Die initial gelesene HTML-Übertragung war eine 90-Minuten-Club-Demo.
|
||
Die Nacht-Fassung normalisiert jetzt `context.role/surface/managerPortrait`
|
||
und zeigt Club-Outdoor mit 90, Club-Indoor mit 40 Minuten sowie National-Outdoor.
|
||
Diese 40 Minuten und die Skalierung synthetischer Ereignisse sind **Dummyregeln**,
|
||
keine bestätigte Enginezeit. Timer, Torschützenformeln und Elf-des-Tages-Wertung
|
||
sind keine Enginevorgabe. Der spätere Adapter darf weder diese Regeln übernehmen noch
|
||
fehlende echte Werte durch die Demo ersetzen.
|
||
|
||
## Verbindliche Entwurfsprinzipien
|
||
|
||
- Daten sind JSON-Objekte, Zahlen mit Einheiten und logische Assetreferenzen.
|
||
Keine HTML-, RML-, CSS- oder SVG-Fragmente aus der Engine. `Text.text` ist
|
||
**Plaintext**; die UI behandelt ihn als Text, nie als Markup.
|
||
- `worldId/worldRevision` bezeichnet den geladenen Datensatz. `careerId` trennt
|
||
Karrieren derselben Welt. `stateRevision` bezeichnet den aktiven Zustand;
|
||
`projectionRevision` zusätzlich Korrektur-/Aggregationsstände. Vor Karriere-
|
||
start dürfen Welt/Karriere unbekannt sein und bleiben `null`.
|
||
- IDs sind stabile Zeichenketten. Manageridentität bleibt über Vereinswechsel,
|
||
Umbenennung und Aufgeben bestehen. Runtime-Slots, Rang, Tabellenposition,
|
||
Bildindex und Anzeigename sind niemals fachliche Identität.
|
||
- Alle Reads sind frei von **Spiel-RNG**, Buchung, Fortschritt und Spielrevision.
|
||
Auswahl, Scrollen, Picker-Abbruch, Theme, Chartschalter und Ticker-Abspieltempo
|
||
bleiben UI-Zustand. Eine existierende C++-„Preview“, die Quoten erzeugt und
|
||
RNG/Zustand fortschreibt, wird ausdrücklich über `quote.request` adaptiert,
|
||
nicht während eines vermeintlich harmlosen Reads aufgerufen.
|
||
- Mutationen tragen `requestId`, Welt-/Karriere-ID, `expectedRevision`,
|
||
Manager-/Team-/Scopeidentität und bei Bedarf Quote-/Live-/Fortsetzungstoken.
|
||
Ownerangaben im JSON sind **keine Autorisierung**: die Session prüft sie gegen
|
||
ihren tatsächlichen aktiven Kontext. Erfolg wird genau einmal publiziert;
|
||
Eine **protokoll-/validierungsbedingte** Ablehnung erhält Zustand, beide RNGs,
|
||
Geld und Revision. Ein fachlich erfolgloser, aber regelgerecht ausgeführter
|
||
Versuch (z. B. Angebot abgelehnt/Abwerben versucht) kann dagegen ein akzeptierter
|
||
Command mit `outcome=offer_rejected` und neuem Zustand sein. Solche Enginefolgen
|
||
werden nicht fälschlich als rollbackpflichtiger Transportfehler ausgegeben.
|
||
- Derselbe `requestId` darf nach Timeout nicht doppelt buchen. Gleiches Payload
|
||
erhält das gespeicherte Ergebnis oder einen eindeutigen Duplikatstatus;
|
||
verändertes Payload bei gleicher ID wird abgewiesen. Aufbewahrungsdauer und
|
||
Verhalten über Neustarts stehen unter D03 zur Entscheidung.
|
||
- `Availability` und `Coverage` trennen fehlend, unvollständig und belegt. `0`
|
||
ist ein bekannter Nullwert; unbekannt ist `null` plus Grund. Fehlende Kader
|
||
erzeugen keine Phantomspieler. Kein fremder Verein wird als Ersatzmanagerteam
|
||
gewählt. `unavailable` darf der Renderer neutral darstellen.
|
||
|
||
## Einheiten, Geld und Zeit
|
||
|
||
`Money={minor, currency, minorUnits}` verwendet eine vorzeichenbehaftete
|
||
**Dezimalzeichenkette** für die kleinste Währungseinheit. `"1500"`, EUR, 2
|
||
bedeutet 15 Euro. Das vermeidet Präzisionsverlust in JS oberhalb von 2^53.
|
||
Dasselbe gilt für uint64-Revisionen und Sequenzen. Werte müssen zusätzlich in
|
||
den vereinbarten int64-/uint64-Grenzen liegen. Dies ist eine Entwurfsentscheidung,
|
||
keine Behauptung einer schon umgestellten Engine; Alternative siehe D01.
|
||
|
||
Die drei Schichten dürfen nicht durch gleichnamige `cash`-Felder vermischt werden:
|
||
|
||
| Schicht | Beispiel 15 Euro | Richtige Grenze |
|
||
| --- | --- | --- |
|
||
| Vorhandene Engine-Reads / bisheriges HTML-Dummy `bank.cash` | `15` ganze Euro | Einmal geprüft nach Minor Units normalisieren. |
|
||
| Neuer JSON-DTO | `{minor:"1500",currency:"EUR",minorUnits:2}` | Exakte kanonische Transportform, keine formatierte Zeichenkette. |
|
||
| Bisheriger HTML-Formatter `submenus.money(n)` | `money(15)` | Erwartet ganze/anzeigefertige Euro, also DTO vorher **gezielt zurück** übersetzen; nicht `money(1500)`. |
|
||
| Nativer Demo-/neuer Money-Formatter | Minor-Unit-Wert `1500` | Bereits Minor Units: nicht noch einmal ×100 skalieren. |
|
||
|
||
Der HTML-Adapter darf daher **kein blindes ×100** übernehmen. Bestehende HTML-
|
||
Statewerte und native Demostände brauchen getrennte, versionierte Adapter.
|
||
Größere Decimalstrings dürfen für Anzeige nicht ungeprüft in einen ungenauen
|
||
JS-Number gewandelt werden. Lokalisierung, Währungssymbol und Nachkommastellen
|
||
gehören an den passenden Formatter, nicht in den Enginebetrag.
|
||
|
||
Aktuelle `read.status.money` und mehrere Engine-C++-Werte sind ganze Engine-
|
||
Euro. Der Adapter konvertiert geprüft mit `10^minorUnits`; er interpretiert sie
|
||
nicht als bereits vorhandene Centwerte. `ContractPlayer.current_monthly_salary`
|
||
und `ContractRequest.monthly_salary` belegen Monatsgehälter; Jahreswert und
|
||
Gesamtlaufzeit sind andere Felder. Quoten enthalten `totalBasis` und `chargesNow`:
|
||
ein Monatsangebot ist keine sofortige Kontobuchung. Zinsbasis, Gebühren,
|
||
Rundung, Aktienkurse, Mengen und Vertragspreise sind je Aktion abzugleichen.
|
||
|
||
Kalendertage sind ISO `YYYY-MM-DD`; Saison-ID, Saisonlabel und Kalenderjahr
|
||
bleiben getrennt. Historische Spieltage werden über `almanac_date()` übertragen.
|
||
Dateizeitstempel benutzen UTC-`date-time`. Livezeit führt Periode, Minute und,
|
||
nur wenn belegt, Sekunden/Nachspielzeit. Indoor- und Verlängerungsperioden dürfen
|
||
nicht auf eine feste 0–90-Prozentachse gequetscht werden. Unklare historische Indoor-Perioden bleiben im Archivbeispiel ausdrücklich unbekannt.
|
||
Für neue Live-Hallenspiele belegt `src/modern/game/driver.cpp` zwei 20-Minuten-Abschnitte;
|
||
maßgeblich bleiben die gelieferten Periodenwerte der tatsächlichen Engine. Abwesenheiten
|
||
führen Wert **und** Einheit: vorhandene Wochenzähler dürfen nicht still in
|
||
exakte Verletzungstage oder Sperrspiele umgedeutet werden.
|
||
|
||
## Vier Manager und das neue Manager-Untermenü
|
||
|
||
Der Sessionkontext enthält bis zu vier Personen und `activeManagerId`.
|
||
`humanOwnership` ordnet Teams der aktiven menschlichen Kontrolle zu; eine
|
||
archivierte Person ist keine aktive Kontrolle. Ein Team kann nicht durch eine
|
||
veraltete Auswahl plötzlich einem anderen Manager gehören. Zwei menschliche
|
||
Manager im selben Spiel ergeben zwei Eingriffsrechte, aber nur **ein** Match.
|
||
|
||
Das neue Untermenü bündelt **Aufgeben**, **Vereinssuche** und **Neuer Spieler**.
|
||
Die Vereinssuche ist vorerst eine als `future_readonly` erklärte Lesecapability.
|
||
Neuer Spieler benutzt den bestehenden Join-Pfad und dessen gesperrte/belegte
|
||
Plätze, keinen zweiten Startflow. Aufgeben zeigt eine revisionsgebundene
|
||
Bestätigung: Bei weiteren Menschen übernimmt die KI das bisherige Team;
|
||
beim letzten Menschen endet die Sitzung mit `last_human_resigned`. Identität,
|
||
Amtszeiten und historische Titel bleiben im separat paginierten `manager_archive`. Das aktive
|
||
Vier-Slot-Limit ist kein Limit für historische Personen. Das Ergebnis enthält
|
||
AI-Handover, neue aktive Person oder `null`, `sessionState` und `terminationReason`.
|
||
**Das ist der neue Nutzervertrag, keine hier implementierte Enginelogik.**
|
||
|
||
Der neue HTML-Kontext `role` wird auf den DTO-Scope, `surface` auf das
|
||
Matchformat und `managerPortrait` ausschließlich auf GUI-Porträtbindung abgebildet.
|
||
Die Dummy-Porträtnummer erzeugt keine dauerhafte Engine-Manager-ID. Aktuell
|
||
normalisiert HTML die Nationalrolle auf Outdoor; ein künftiger Enginecommand
|
||
muss einen nicht unterstützten National-/Indoor-Kontext ausdrücklich ablehnen,
|
||
statt eine andere Sportart heimlich zu simulieren.
|
||
|
||
Die 0.3-Auswahl erlaubt derzeit deutsche Vereinsmanager und die belegte
|
||
Deutschland-Nationalrolle; ausländische Clubs bzw. andere Nationaltrainer sind
|
||
nicht pauschal als wählbar anzunehmen. Im National-Schreibtisch sind TOTO,
|
||
Bank, Trainingslager, Training und Stadion durch den vorhandenen Enginekontext
|
||
gesperrt (`ui/desk_state.cpp`); zusätzliche POC-Sperren für Sponsoren, Transfers,
|
||
Verträge und Umfeld sind davon getrennte UI-Policy. `menuAvailability` trägt den
|
||
konkreten Grund, statt nur `club=null` zu deuten. Der synthetische National-
|
||
Managerfall steht für diese Deutschland-kompatible Rolle; andere Nationalteams
|
||
bleiben als Gegner darstellbar.
|
||
|
||
Indoor unterscheidet `rosterSize`, `rosterLimit`, `onFieldCount`,
|
||
`onFieldLimit` und `benchLimit`. Belegt sind sechs gleichzeitige Feldpositionen und elf
|
||
Zeilen im Rotationsplan (`game/lineup.cpp`); eine 11er-Feldregel aus der Outdooransicht darf
|
||
nicht übernommen werden. `benchLimit=5` im Fixture ist die Partneraufteilung des synthetischen 11/6-Beispiels; sie erklärt keine allgemeine Kaderobergrenze, keine Aussage über einen
|
||
neuen Wechselmodus. Wechselanzahl und Wiedereinwechselbarkeit bleiben D11.
|
||
|
||
## Pagination, Live und Nachspiel
|
||
|
||
Listen haben max. 200 Zeilen pro Seite. Cursor sind opak und binden Filter,
|
||
Sortierung, Owner, Revision und die letzte stabile ID. Sortieren findet vor dem
|
||
Paginieren statt, gleiche Metrik hat einen ausdrücklich bestimmten Rang und
|
||
ID-Tiebreak. Top-3-Karten und Restliste müssen denselben Snapshot verwenden.
|
||
Ein alter Cursor führt zu `invalid_cursor`/Neuabfrage statt zu Mischständen.
|
||
Das Schema validiert die Form, nicht die Serversemantik eines Cursors.
|
||
|
||
Live liefert `presentationId`, `scopeToken`, monotone `sequence`, Match-/Event-
|
||
IDs, beobachtete Spiele und Managerbezüge. Ein Managerwechsel, Nachspiel oder
|
||
Halbzeitwechsel darf einen alten Eingriff nicht neu zuordnen. Verlorene oder
|
||
falsch geordnete Deltas verlangen Resync; Wiederholung darf keine Tore doppeln.
|
||
Präsentationspause/Abspieltempo und Engine-Fortschritt bleiben getrennt.
|
||
|
||
Postmatch enthält die fünf vorhandenen HTML-Schritte Ergebnisse, Bericht,
|
||
Elf des Tages, Übersicht und Tabelle. Rückblick/Seek verändert keine Saison.
|
||
Nur `postmatch.continue` mit passendem Fortsetzungstoken darf die Engine genau
|
||
einmal fortsetzen. Auszeichnungen und Tabellen sind autoritative Projektionen;
|
||
keine UI-Torformel, 3-Punkte-Regel oder nominierte Elf wird nachgerechnet.
|
||
Welche Schritte in Pokal/National/Indoor verfügbar sind, liefert Capability
|
||
statt eines leeren, scheinbar fertigen Ligabilds.
|
||
|
||
## Übergabe und Abnahme
|
||
|
||
Claude kann zunächst Umschlag/IDs/Einheiten und die P0-Entscheidungen festlegen,
|
||
dann je Menü einen Sessionadapter samt Read-/Command-Tests liefern. Root bindet
|
||
die native UI daran an. Die bestehenden Enginefunktionen und Classic bleiben
|
||
hier unverändert. Je Lieferung sind Quelle, unterstützte Kontexte, Fehler,
|
||
Revision, RNG-Unveränderlichkeit der Reads und atomare Negativfälle nachzuweisen.
|
||
Eine bestandene Schema-QA bestätigt nur diesen Vertragsentwurf, keinen bereits
|
||
lauffähigen Engineadapter, kein OBS-Migrationsformat und keine native Match-QA.
|
||
|
||
Die Schemadatei und alle Beispiel-DTOs lassen sich ohne Engine oder Spieldaten
|
||
mit den Generatoren unter `tools/` reproduzieren. Der Validator benötigt Python
|
||
mit `jsonschema`; er validiert ausschließlich diese begrenzten Designfixtures.
|