Draft Modern UI JSON contracts and almanac requirements (by Codex)
This commit is contained in:
1 parent
a207b0129e
commit
c2fb772c04
67 files changed
+27796
No files matched your search
@@ -0,0 +1,226 @@
|
||||
<!-- 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 |
|
||||
| --- | --- |
|
||||
| [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. Die Indoor-Periodenlängen bleiben im Beispiel ausdrücklich unbekannt;
|
||||
maßgeblich sind die 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 Personen auf dem Feld und elf
|
||||
Kaderplätze (`game/lineup.cpp`); eine 11er-Feldregel aus der Outdooransicht darf
|
||||
nicht übernommen werden. `benchLimit=5` im Fixture ist die restliche
|
||||
Kapazitätsaufteilung des synthetischen 11/6-Beispiels, 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.
|
||||
Reference in new issue
Block a user