Backend-Autoritäres Laufzeit-Refactoring

Was macht Backend-Autoritäres Laufzeit-Refactoring?

Führe das Refactoring nur durch, wenn du genau sagen kannst, wo die Ausführungswahrheit lebt und wie die UI sie liest.

Wann verwenden

• Die UI synthetisiert Graphen, Phasen oder Provider-Auswahlen, die das Backend nicht versteht.
• Ein Neustart oder eine erneute Verbindung ändert den sichtbaren Laufzeitzustand, weil das Frontend die Autorität zwischengespeichert hat.
• Alte und neue Schemata, Starterformate oder Knotentypen koexistieren im aktiven Authoring-Pfad.
• Genehmigung, Überprüfung oder nachgelagerte Ausführung hängen von einer Frontend-Rekonstruktion ab.

Nicht geeignet für

• Kosmetische visuelle Bereinigung ohne Änderung der Laufzeitbesitzer.
• Isolierte Komponenten-Refactorings, bei denen der Backend-Vertrag bereits autoritär ist.
• Auslieferung neuer Geschäftsfunktionen, bevor die Nahtstelle geteilter Autorität entfernt wurde.
• Reine Backend-Performance-Arbeiten, wenn die Architektur bereits eine einzige Quelle der Wahrheit hat.

Entscheidungspunkte

flowchart TD
  A[Anfrage zum Workflow-Refactoring] --> B{Kann die UI immer noch Laufzeitwahrheit erfinden?}
  B -->|Nein| C[Verwende eine engere Domäne oder UI-Fähigkeit]
  B -->|Ja| D[Inventarisiere Befehls-, Abfrage- und Ereignisbrüche]
  D --> E{Kann jede Benutzeraktion einem Befehl, einer Abfrage oder einem Ereignis zugeordnet werden?}
  E -->|Nein| F[Friere den Vertrag ein, bevor Feature-Arbeit beginnt]
  E -->|Ja| G[Trenne den Projektionszustand vom Backend-eigenen Zustand]
  G --> H{Sind Legacy-Kompatibilitätspfade noch aktiv?}
  H -->|Ja| I[Verschiebe sie in Migrationskanten oder lösche sie]
  H -->|Nein| J[Füge Evaluatoren, wiedergabesichere Startabfragen und Ereignisabonnements hinzu]
  I --> J
  J --> K[Validiere Wiederherstellung, Genehmigung und nachgelagerte Bereitschaft]

Verwende zuerst dieses Routing-Modell:

• Wenn die UI nicht als Befehl -> Backend-Übergang -> Abfrage- oder Ereignisprojektion beschrieben werden kann, ist die Nahtstelle noch falsch.
• Wenn sich ein „temporärer Kompatibilitäts“-Pfad im heißen Pfad befindet, behandle ihn als Refactoring-Schuld, nicht als Feature.
• Wenn ein Neustart oder eine erneute Verbindung den sichtbaren Zustand nicht allein aus der Backend-Wahrheit rekonstruieren kann, ist das Refactoring unvollständig.

Arbeitsmethode

1. Inventarisiere die geteilte Intelligenz

Finde alle Stellen, an denen die UI:

• Ausführungswahrheit erzeugt oder mutiert
• Phasen erfindet, die das Backend nicht kennt
• Ausführung in aktiven Codepfaden simuliert
• Sowohl alte als auch neue Schemata im selben Authoring-Pfad beibehält
• Abstrakte Routing-Ebenen mit genauen Provider-IDs vermischt

2. Friere den Vertrag ein

Definiere nur drei Klassen:

• Befehle: starten, stoppen, genehmigen, fortsetzen, mutieren
• Abfragen: Startzustand, Prüf-Payload, Ausführungs-Snapshot, Provider-Health
• Ereignisse: autoritäre Übergänge, Bewerterentscheidungen, Gate-Status, Wiedergabe-Marker

Wenn eine UI-Aktion nicht als eine dieser Klassen ausgedrückt werden kann, ist die Architektur noch unscharf.

3. Normalisiere die Zustandsverantwortung

Teile Stores auf in:

• Vertragseingabezustand
• Backend-Snapshot-Projektionszustand
• UI-Layout-Zustand

Erlaube keinem Store, sowohl Laufzeitwahrheit als auch Layout-Belange zu besitzen.

4. Lösche aktive Kompatibilitätsbrüche

Bevorzuge Löschen gegenüber „beides vorerst unterstützen“.

Typische Löschungen:

• Einzel- und Plural-Schema-Kompatibilität im aktiven Authoring
• Browser- oder Demo-Simulation im aktiven Desktop-Laufzeitsystem
• Veraltete Knotentypen im Hauptpfad
• Doppelte Prüfzusammenfassungen
• Mehrere Starter- oder Importformate

5. Füge Evaluatoren hinzu, bevor du dem Refactoring vertraust

Jeder Implementierungsknoten sollte haben:

• einen lokalen Ausgabe-Evaluator für Korrektheit
• einen nachgelagerten Bereitschafts-Evaluator für Vertragssicherheit
• einen Neustart- oder Wiederverbindungspfad, der aus der Backend-Wahrheit rehydriert, nicht aus Frontend-Schätzungen

Fehlermodi

Projektion, die als Autorität auftritt

Symptom: Die UI sieht „schreibgeschützt“ aus, setzt aber leise Phasen-, Graph- oder Provider-Wahrheit lokal zusammen.

Behebung: Verschiebe diese Logik in Backend-Befehle oder -Abfragen und behandle das Frontend als Projektor.

Verkalkung des Kompatibilitätsbrüches

Symptom: „Beides vorerst unterstützen“ bleibt wochenlang im heißen Pfad und wird zur tatsächlichen Architektur.

Behebung: Verschiebe Kompatibilität auf unidirektionale Migrationskanten mit explizitem Löschdatum oder entferne sie jetzt.

Genehmigung ohne Prüfbarkeit

Symptom: Ein Mensch kann Arbeit genehmigen, die er nicht prüfen kann, weil die Prüf-Payload unvollständig oder vom Frontend synthetisiert ist.

Behebung: Das Backend muss die exakte Prüf-Payload emittieren; die UI rendert sie nur.

Wiedergabefeindlicher Start

Symptom: Ein Neustart der App ändert den sichtbaren Zustand oder verliert die Gate-Position, weil das Frontend die Autorität zwischengespeichert hat.

Behebung: Der Start muss eine Abfrage gegen die Backend-Wahrheit plus Ereigniswiedergabe sein, keine Store-Rekonstruktion.

Erkennungsmerkmal

Wenn ein Neustart der App den sichtbaren Laufzeitzustand ohne ein neues Backend-Ereignis ändert, ist die Autorität immer noch geteilt.

Ausgearbeitetes Beispiel

Tauri-Workflow-Editor mit Frontend-eigener Phasenlogik

Problem:

• React-Stores authored den Graphen, leiteten den Phasenzustand ab und normalisierten Provider-Ebenen.
• Die Backend-Ausführung verwendete einen anderen Vertrag, sodass Prüf- und Neustartflüsse auseinanderdrifteten.

Refactoring-Pfad:

1. Inventarisiere jede Stelle, an der die UI Ausführungswahrheit erfand.
2. Reduziere Laufzeitinteraktionen auf Befehle, Abfragen und Ereignisse.
3. Verschiebe Provider-Normalisierung und Phasenübergänge hinter Backend-Befehle.
4. Lösche Starter-Format-Vereinigungen aus dem aktiven Authoring-Pfad.
5. Füge Evaluator-Gates hinzu, sodass nachgelagerte Arbeit nur von Backend-validierten Ausgaben ausgeht.

Erfolgsbedingung:

• Beim Neustart rekonstruiert die UI denselben sichtbaren Zustand aus dem Backend-Snapshot plus Ereignissen.
• Genehmigungsbildschirme rendern eine vom Backend emittierte Prüf-Payload, keine React-Rekombination.

Fork-Anleitung

Forke, wenn die Arbeit sich sauber trennen lässt:

• Vertragsspur: Inventarisiere geteilte Autoritätsbrüche und definiere Befehle, Abfragen und Ereignisse.
• Löschspur: Entferne Kompatibilitätsschichten, veraltete Knotentypen und Starter-Format-Vereinigungen.
• Verifikationsspur: Füge Evaluator-Gates, Wiedergabetests und Neustart- oder Wiederverbindungsabdeckung hinzu.

Behalte endgültige Besitzentscheidungen in der übergeordneten Spur, sodass ein Akteur entscheidet, was das Backend wirklich besitzt.

Qualitätstore

• Die UI kann Graph-, Phasen-, Provider- oder Gate-Wahrheit nicht lokal erfinden.
• Jede Benutzeraktion ist einem Befehl, einer Abfrage oder einem Ereignis zugeordnet.
• Der Laufzeitzustand überlebt Neustart und erneute Verbindung allein aus der Backend-Wahrheit.
• Prüf- und Genehmigungs-Payloads werden vom Backend emittiert und von der UI gerendert.
• Kompatibilitätslogik lebt nur auf Migrationskanten, nicht im aktiven Pfad.
• Die nachgelagerte Ausführung stoppt bei Vertragsverletzung des Upstreams.
• Exakte Provider-IDs und Modellauswahlen sind an der Vertragsgrenze sichtbar.
• Tests decken Neustart-, Wiederverbindungs-, Genehmigungs- und Evaluatorfehlerpfade ab.

Referenzkarte

• references/architecture-patterns.md — Backend-eigene Workflow-Vertragsmuster und Zustandsbesitz-Trennungen.
• references/windags-lessons.md — konkrete Lehren aus einer echten Migration geteilter Autorität zur Laufzeit.