Backend und Frontend einer Erzeugungs-App über OpenAPI synchron halten

## Nach jeder Backend-API-Änderung OpenAPI-Typen und Clients neu erzeugen Führe nach jeder Änderung einer Backend-API den OpenAPI-Aktualisierungsbefehl des Repositorys aus. Behandle das erzeugte Schema und die Frontend-Typen als Teil derselben Änderung und nicht als spätere Aufräumarbeit. Der Frontend-Code muss Backend-Endpunkte über den erzeugten OpenAPI-Client aufrufen. Füge keine handgeschriebenen Dienstkapseln hinzu, die erzeugte Anfrage- und Antwortverträge doppelt abbilden. Trenne die Zuständigkeiten im Backend strikt: - Die API-Schicht wertet Eingaben aus, führt Authentifizierung und Autorisierung durch und stellt Antworten zusammen. - Die Dienstschicht ist für Geschäftsregeln, Zustandsübergänge und Datenkoordination zuständig. Lege schichtübergreifende Erzeugungsverträge, einschließlich Eingabe- und Ausgabe-Datenübertragungsobjekten sowie Anbieterkonfigurationen, in einem gemeinsamen Vertragsmodul ab. Aufgabenmodule sollen nur Aufgabenkapselung, Zuweisung und Ausführungskoordination enthalten und keine gemeinsamen DTOs definieren. Integrationsmodule dürfen von gemeinsamen Verträgen abhängen, aber nicht von aufgabeninternen Typmodulen. Wenn sich eine API, ein Typ oder ein Zustandsmodell ändert, aktualisiere gemeinsam die Backend-Implementierung, das OpenAPI-Dokument, die erzeugten Frontend-Typen, die Client-Nutzung und die unmittelbar zugehörige Dokumentation. ## Jede Funktion kommentieren und aktuelle Fakten von Plänen in der Dokumentation trennen Wenn Frontend-Stile mehr als einmal vorkommen, verwende bevorzugt eine wiederverwendbare Komponente oder eine gemeinsame Stilstruktur statt einer weiteren Kopie. Jede Funktion, Klasse oder vergleichbare Codeeinheit benötigt einen Kommentar, der erklärt, was sie tut und warum sie existiert. Komplexe Logik soll außerdem relevante Parameter, Rückgabeverhalten und wesentliche interne Entscheidungen dokumentieren. Halte Kommentare und Implementierung synchron. Ordne Dokumentation vor dem Schreiben ein: - `guide` erklärt, wie eine Aufgabe ausgeführt oder eine Fähigkeit eingebunden wird. - `architecture` beschreibt das derzeit implementierte System. - `plans` dokumentiert zukünftige Arbeiten, gestaffelte Aufgaben und vorgeschlagene Änderungen. - `reference` enthält stabile Fakten zum Nachschlagen. - `blog` enthält Versionshinweise. Schreibe aktuelle Grenzen, implementierte Zustandsübergänge und tatsächliches Verhalten in die architecture-Dokumentation. Noch in Planung oder Umsetzung befindliche Arbeiten gehören in plans. Betriebsanweisungen und Entwicklungsabläufe gehören in guide. Vermische aktuelle Tatsachen und zukünftige Absichten nicht in einer einzelnen Anleitung. Trenne sie zwischen architecture und plans, auch wenn sie dasselbe Thema betreffen. Ändere abgeschlossene historische Versionshinweise nur, wenn die Aufgabe dies ausdrücklich verlangt. ## Die Aufgabenübersicht schlank halten und jeder Oberfläche eine eigene Aufgabe geben Teile den primären Benutzerablauf in Oberflächen mit klaren Zuständigkeiten: - Eine Vorbereitungsseite extrahiert Fachdaten, bestätigt Kandidaten, korrigiert Grundinformationen und setzt das Element auf `ready`. - Ein Erzeugungsarbeitsbereich prüft die Ausgabebereitschaft, verwaltet wichtige Ressourcen und Parameter, startet die Erzeugung und zeigt Ergebnisse an. - Eine Aufgabenübersicht zeigt ausschließlich leichte, allgemeine Aufgabeninformationen wie Zustand, Fortschritt, Erfolg, Fehlschlag, Abbruch und einen Rückkehrlink. Lege fachbezogene Zusammenfassungen, Kontext zur Fehlersuche bei Eingabeaufforderungen, Ressourcenzuordnungen oder andere umfangreiche Details nicht in der allgemeinen Aufgabenübersicht ab. Bewahre sie im jeweils zuständigen Vorbereitungs-, Erzeugungs-, Ausführungs- oder Diagnosebereich auf. Wenn Extraktionswerkzeuge im Erzeugungsarbeitsbereich verfügbar bleiben, stelle sie nur als Schnellzugriff oder Diagnosewerkzeug bereit. Sie dürfen die Vorbereitungsseite nicht als wichtigste Bestätigungsoberfläche ersetzen. Wenn sich eine Zuständigkeitsgrenze ändert, aktualisiere sowohl die betroffene Benutzeroberfläche als auch die architecture-Dokumentation. Eine Neugestaltung der Aufgabenübersicht darf sie nicht in eine neue Geschäftsdetailseite verwandeln. ## Den Elementstatus nur für die Bestätigung nutzen, nicht für den Erzeugungsfortschritt Verwende den Hauptzustand des Fachelements ausschließlich für den Informationsbestätigungszustand: - `pending` bedeutet, dass Extraktions- oder Bestätigungsarbeit aussteht. - `ready` bedeutet, dass die erforderlichen Informationen bestätigt sind und die nachfolgende Vorbereitung beginnen kann. Verwende diesen Zustand nicht für die Erzeugung zur Laufzeit. Werte wie `generating` gehören zum Aufgabensystem und zur Laufzeitzusammenfassung. Stelle die Ausgabebereitschaft als eigene Dimension dar. Dass ein Element für die nachfolgende Vorbereitung `ready` ist, garantiert nicht, dass alle Bedingungen für die Erzeugung erfüllt sind. Jede Benutzeroberfläche muss unterscheiden zwischen: 1. Informationsbestätigungszustand; 2. Laufzeitaufgabenzustand; 3. Bereitschaft zur Ausgabeerzeugung. Wenn sich die Zustandsbedeutung ändert, synchronisiere Backend-Verhalten, OpenAPI, erzeugte Frontend-Typen, Zustandsbeschriftungen, Navigationsbedingungen und Entwicklungsdokumentation. ## Nutzer nach der Bestätigung von der Vorbereitungsseite zum Erzeugungsarbeitsbereich führen Der Standardablauf lautet: 1. Arbeitselemente aus Quellinhalten extrahieren; 2. extrahierte Ressourcen, Dialoge oder andere erforderliche Informationen auf der Vorbereitungsseite bestätigen und korrigieren; 3. für wichtige Ressourcen, Referenzmaterial, Ausgabeparameter und Bereitschaftsprüfungen in den Erzeugungsarbeitsbereich wechseln; 4. die Erzeugung aus dem Erzeugungsarbeitsbereich starten; 5. Ergebnisse im Facharbeitsbereich prüfen und die Aufgabenübersicht nur für allgemeinen Aufgabenfortschritt verwenden. Die Vorbereitungsseite ist für Extraktion, Bestätigung und Korrektur zuständig. Der Erzeugungsarbeitsbereich ist für Erzeugungsvorbereitung, Ausführung und Ergebnisprüfung zuständig. Leite den Benutzer nach erfolgreicher Vorbereitung eindeutig zum Erzeugungsarbeitsbereich. Wenn dieser feststellt, dass ein Element nicht `ready` ist, führe den Benutzer mit einer klaren Erklärung zur Vorbereitung zurück. Gib diesem Ablauf bei Änderungen an Interaktionen Vorrang. Komfort-Schnellzugriffe dürfen weder den vorgesehenen nächsten Schritt verschleiern noch Vorbereitung und Erzeugung in einer mehrdeutigen Oberfläche zusammenführen. ## architecture-Dokumente bei jeder Änderung anpassen und in Versionshinweisen direkt nutzbare Migrationsschritte nennen Die architecture-Dokumentation enthält nur Verhalten, das derzeit tatsächlich gilt. Plans enthält laufende Arbeiten, gestaffelte Aufgaben, Prioritäten und zukünftige Ausführungswege. Wenn sich Codeverhalten, Zustandsbedeutung oder Seitenzuständigkeiten ändern, aktualisiere die architecture-Dokumentation in derselben Arbeit. Wenn sich Umfang, Priorität oder Reihenfolge eines Plans ändern, aktualisiere plans. Ein umgesetzter Plan soll in architecture übergehen oder zu einem Versionshinweis werden. Betrachte Arbeiten mit veralteter architecture- oder plans-Dokumentation als unvollständig. Versionshinweise müssen Kopfmetadaten für `title`, `date`, `description`, `tags` und `authors` enthalten. Verwende eine feste Abschnittsreihenfolge und lasse nur nicht zutreffende Abschnitte aus: 1. Höhepunkte; 2. Hinzugefügt, geändert und behoben; 3. Inkompatible Änderungen und Abkündigungen; 4. Sicherheit und bekannte Probleme; 5. Migrationsanleitung und Rücksetzhinweise; 6. Kompatibilitätsmatrix, Prüfungsbefehle und Aktualisierungsprüfliste; 7. Quellen, Hinweise für Mitwirkende und Danksagungen. Schreibe Versionshinweise aus Sicht der Projektpflege: Stelle Schlussfolgerungen und ausführbare Informationen voran, verwende kurze Absätze und Listen und halte Begriffe konsistent. Trenne neue Fähigkeiten, Verhaltensänderungen, Kompatibilitätsrisiken und bekannte Probleme klar voneinander. Migrationsschritte, Rücksetzschritte und Prüfungsbefehle müssen unmittelbar verwendbar und dürfen nicht vage sein. ## Erst abschließen, wenn erzeugte Typen und Dokumentation zum Code passen Die Arbeit ist nur abgeschlossen, wenn alle zutreffenden Bedingungen erfüllt sind: 1. Die Implementierung ist vorhanden, ohne offensichtliche Platzhalter oder veraltete Kompatibilitätsreste. 2. Neue und geänderte Funktionen und Klassen besitzen genaue, nützliche Kommentare. 3. API-Änderungen haben OpenAPI, erzeugte Frontend-Typen und die Nutzung des erzeugten Clients aktualisiert. 4. Aktuelles Verhalten ist in der architecture-Dokumentation und zukünftige Arbeit in plans abgebildet. 5. Die Zuständigkeiten von Vorbereitung, Erzeugung und Aufgabenübersicht bleiben getrennt. 6. Frontend-Änderungen bestehen die TypeScript-Prüfung des Repositorys ohne Ausgabedateien. 7. Backend-Änderungen bestehen die zugehörigen Tests oder mindestens die dokumentierten Syntax- und Importprüfungen. 8. Der Abschlussbericht nennt die Änderungen und die bestandenen Prüfungen. 9. Verbleibende Arbeiten oder weitere Empfehlungen werden getrennt aufgeführt. Melde die Arbeit nicht als abgeschlossen, solange Code, Verträge, erzeugte Typen, Dokumentation, Zustandsbedeutung oder Arbeitsablaufoberflächen nicht übereinstimmen.