Files
Dreierpack-Manager/docs/new_ui/integration/README.md
T

15 KiB
Raw Blame History

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 Schlanker Einstieg und Lieferreihenfolge für die erste echte Anbindung
Schemas JSON Schema 2020-12; gemeinsame Typen, Readmodels, Kommandos, Fehler und Ergebnisse
Index Namen der vorgeschlagenen Reads und Commands
Menüvertrag 47 Menü-/Auswertungsbereiche mit sichtbaren Daten und Code-/HTML-Quellen
Almanach und Auswertungen Ereignisse, Identitäten, Vollständigkeit, Korrekturen, Aggregationen und notwendige Zusatzledger
Pressevertrag Semantische Events, unveränderliche DE/EN-Snapshots und Lösch-Dedupe
Offene Entscheidungen Priorisierte Rückfragen für Claude/Engine, ohne stillschweigende Antworten
Beispiele 53 Dateien: vier Manager, Verein/National, ET, PSO, Indoor, unbekannte Altphasen, Geschäftsdaten und Aufgeben
Quellbasis Getrennte Revisionen und Hashes der geprüften Vertragsquellen
QA 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.