Files

228 lines
15 KiB
Markdown
Raw Permalink 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 -->
# 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.