leistungsbilanz-ts/docs/revit-requirements-llm-context.md

Kontext für die Revit-Anforderungsplanung

Zweck dieser Datei

Diese Datei ist eine kompakte Übergabe an ein anderes LLM. Sie soll dabei helfen, gemeinsam mit dem Anwender die fachlichen und technischen Anforderungen für einen zukünftigen Revit-Datenaustausch zu klären.

Die Revit-Schnittstelle ist noch nicht implementiert. Das LLM soll zunächst den tatsächlichen Arbeitsablauf erfragen, Unklarheiten sichtbar machen und daraus eine neue, überprüfbare Arbeitsanweisung erstellen. Es soll weder ein Dateiformat noch ein Datenbankschema oder eine UI ungefragt festlegen.

Produkt und fachliches Modell

Leistungsbilanz ist eine Webanwendung für die elektrische Ausführungsplanung. Ihr Kern ist ein tabellenähnlicher Stromkreislisten-Editor für Verteilungen.

Das unterstützte Laufzeitmodell ist:

Project
├── Floor
│   └── Room
├── ProjectDevice
└── DistributionBoard
    └── CircuitList
        └── CircuitSection
            └── Circuit
                └── CircuitDeviceRow

Wichtige fachliche Grenzen:

• Ein Circuit ist nicht dasselbe wie eine Gerätezeile.
• Ein Stromkreis kann null, eine oder mehrere CircuitDeviceRow enthalten.
• BMK (equipmentIdentifier), Schutz- und Kabeldaten gehören zum Stromkreis.
• Menge, Einzelleistung, Gleichzeitigkeitsfaktor, cosPhi, Raum, Kostengruppe und Kategorie gehören zur Gerätezeile.
• Ein ProjectDevice ist eine wiederverwendbare, projektbezogene Vorlage.
• Eine Gerätezeile kann mit einem Projektgerät verknüpft sein, behält aber lokale Werte und ausdrücklich erfasste Abweichungen.
• Änderungen eines Projektgeräts überschreiben verknüpfte Zeilen niemals automatisch. Eine Synchronisierung benötigt Vorschau und Benutzerauswahl.
• Manuelle, nicht mit einem Projektgerät verknüpfte Gerätezeilen sind regulär erlaubt.
• Bestehende BMKs und stabile UUIDs dürfen nicht automatisch verändert werden.
• Neunummerierung ist immer eine ausdrückliche Benutzeraktion.
• IFCGUID darf nicht als BMK oder als Ersatz für eine interne UUID verwendet werden.

Für einen späteren Revit-Austausch besonders relevante Daten sind:

• Projekt: Name, interne/externe Projektnummer, Bauherr, Beschreibung, Projektspannungen.
• Geschoss und Raum: interne UUID, Name beziehungsweise Raumnummer und Raumname.
• Verteilung: interne UUID, Name, Etage, Netzart und Gleichzeitigkeitsfaktor.
• Stromkreis: interne UUID, BMK, Anzeigename, Bereich, Schutz-, Kabel-, Spannungs-, Steuerungs-, Status- und Bemerkungsdaten.
• Gerätezeile: interne UUID, optionale Projektgeräteverknüpfung, Name, Anzeigename, Phasenart, Anschlussart, Kostengruppe, Kategorie, Geschoss, Raum, Menge, Einzelleistung, Gleichzeitigkeitsfaktor, cosPhi und Bemerkung.
• Projektgerät: interne UUID sowie die wiederverwendbaren Gerätewerte.

Die Phasenart ist fachlich 1-phasig oder 3-phasig. Die Spannung wird daraus und aus den Projekteinstellungen abgeleitet; freie Sonderspannungen sind im aktuellen Produkt nicht vorgesehen.

Aktuelle technische Architektur

• Frontend: Next.js App Router, React und TypeScript unter src/app und src/frontend.
• API: Express und Zod unter src/server.
• Fachregeln und typisierte Commands: src/domain.
• Persistenz: SQLite, Drizzle und Repository-Adapter unter src/db.
• Laufzeitkomposition konkreter Repositories: src/server/composition.
• Lokaler Betrieb: Browser/Next.js auf Port 3001, Express-API auf Port 3000, SQLite-Datei unter data/leistungsbilanz.db.
• Docker Compose wird für die lokale Entwicklung unterstützt.
• PostgreSQL und Mehrbenutzerbetrieb sind noch nicht umgesetzt.

Der zentrale Editor liegt unter:

src/app/projects/[projectId]/circuit-lists/[circuitListId]/tree-edit/page.tsx
src/frontend/components/circuit-tree-editor.tsx

Frontend-Aktionen werden als validierte API-Commands ausgeführt. Fachregeln liegen in Domain-Services; konkrete SQLite-Zugriffe bleiben in Persistenzadaptern. Neue Revit-Fachlogik darf deshalb nicht direkt von better-sqlite3, React-Komponenten oder globalen Datenbankinstanzen abhängen.

Revisionen, Undo/Redo und Sicherungspunkte

Alle normalen projektbezogenen Änderungen laufen über eine gemeinsame Command- und Transaktionsgrenze:

Fachänderung + inverses Kommando + Revision + Undo/Redo-Übergang

Diese Bestandteile werden atomar geschrieben oder vollständig zurückgerollt. Jedes Projekt besitzt eine monoton steigende currentRevision. Schreibbefehle geben die erwartete Revision mit, damit veraltete Clients keine neueren Änderungen überschreiben.

Undo/Redo ist projektweit persistent und funktioniert nach Reload oder Anwendungsneustart. Zusätzlich gibt es:

• eine unveränderliche Revisions-Timeline;
• benannte und automatische logische Projektsnapshots;
• wiederherstellbare Snapshots mit Prüfsumme;
• einen portablen, versionierten JSON-Projekttransfer.

Ein angewendeter Revit-Import muss später dieselbe Integritätsgrenze verwenden: Die bestätigten Änderungen sollen als ein nachvollziehbarer Projekt-Command beziehungsweise als ein fachlich definierter Änderungssatz atomar, revisioniert und rückgängig machbar sein.

Klare Abgrenzung zum vorhandenen JSON-Projekttransfer

Der vorhandene JSON-Export/-Import überträgt den vollständigen internen Projektzustand. Er dient Sicherung, Wiederherstellung und Duplizierung eines Projekts innerhalb von Leistungsbilanz.

Dieser Projekttransfer ist kein Revit-Austauschformat. Er enthält interne Strukturen und UUIDs und soll nicht ohne bewusste Entscheidung als Grundlage für CSV-Dateien oder Revit-Parameter verwendet werden.

Der zukünftige Revit-Workflow soll dagegen externe Modellobjekte anhand stabiler externer Identitäten wiedererkennen, ausgewählte Planungswerte zuordnen und Ergebnisse so exportieren, dass Revit sie wieder den richtigen Objekten zuweisen kann.

Bereits vereinbarte Leitplanken für den externen Modellaustausch

Diese Punkte gelten als Architekturvorgaben, noch nicht als fertiges Implementierungsdesign:

• Ein Import schreibt niemals ungeprüft direkt in Stromkreise oder Gerätezeilen.
• Eingelesene Daten landen zuerst in einem Staging-/Vorschaubereich.
• Vor der Übernahme werden neue, geänderte, fehlende, doppelte und widersprüchliche Objekte angezeigt.
• Wiederholte Importe müssen Objekte deterministisch anhand der externen Quelle und einer stabilen Identität, voraussichtlich IFCGUID, erkennen.
• Die Eindeutigkeit einer IFCGUID ist mindestens auf Projekt und externe Modellquelle begrenzt; die genaue Quellendefinition ist noch zu klären.
• Importierte Quellwerte und lokal in Leistungsbilanz geplante Werte müssen unterscheidbar bleiben.
• Lokale Planungswerte dürfen niemals still überschrieben werden.
• Verknüpfungen zwischen externen Objekten und internen Fachobjekten müssen ausdrücklich modelliert werden.
• Fehlende oder widersprüchliche Identitäten werden gemeldet und niemals automatisch einem anderen Objekt zugeordnet.
• Ein Export bewahrt IFCGUID und erforderliche Quellidentitäten, damit Revit die Werte deterministisch zurückschreiben kann.
• Ein Export bezieht sich auf eine bekannte Projektrevision.
• Große Datenmengen allein erzwingen noch keinen Wechsel von SQLite zu PostgreSQL. PostgreSQL wird relevant bei Mehrbenutzerbetrieb, zentralem Serverbetrieb oder unabhängigen Hintergrundjobs.

Als mögliche, aber noch nicht beschlossene Konzepte wurden bisher genannt:

• ExternalModelSource
• ExternalImportBatch
• ExternalModelObject
• ExternalObjectLink
• ExternalParameterMapping
• ExternalExportBatch

Diese Namen beschreiben Verantwortlichkeiten. Das andere LLM darf sie hinterfragen und verbessern, soll sie aber nicht als bereits vorhandene Tabellen behandeln.

Auftrag an das andere LLM

Erarbeite die Anforderungen dialogorientiert mit dem Anwender. Beginne mit dem realen Ablauf in Revit und kläre danach schrittweise mindestens:

1. Welche Revit-Objekte beziehungsweise Kategorien werden exportiert?
2. Wie entsteht die Ausgangsdatei in Revit und wie sieht sie technisch aus (CSV-Dialekt, Trennzeichen, Encoding, Dezimalformat, Kopfzeilen, Revit-Versionen)?
3. Welche Identitäten stehen zur Verfügung: IFCGUID, Revit ElementId, Typ-ID, Modell-/Dateikennung oder weitere Schlüssel?
4. Wie werden Hauptmodell, Teilmodelle, verknüpfte Modelle, Modellkopien und aktualisierte Revit-Dateien unterschieden?
5. Welche Parameter kommen aus Revit und welche Werte werden ausschließlich in Leistungsbilanz geplant?
6. Welche internen Ziele können externe Objekte erhalten: Projektgerät, Gerätezeile, Stromkreis, Raum, Verteilung oder weitere Entitäten?
7. Werden externe Objekte einzeln oder gesammelt einem Stromkreis, Projektgerät, Raum oder einer Verteilung zugeordnet?
8. Welche Werte sollen nach Revit zurückgeschrieben werden, in welchen Einheiten und unter welchen Revit-Parameternamen?
9. Muss die ursprüngliche Datei einschließlich unbekannter Spalten, Zeilenreihenfolge und Formatierung erhalten werden, oder darf eine neue Rückgabedatei erzeugt werden?
10. Wie sollen Spalten-/Parametermappings erstellt, gespeichert, wiederverwendet und zwischen Projekten geteilt werden?
11. Was gilt bei erneutem Import für neue, geänderte, gelöschte, verschobene, doppelte oder nicht mehr sichtbare Revit-Objekte?
12. Wer gewinnt bei Konflikten zwischen neuem Revit-Wert und lokaler Änderung? Welche Konflikte dürfen automatisch gelöst werden und welche benötigen eine Auswahl?
13. Welche Vorschau, Filter, Sammelaktionen und Bestätigungen benötigt der Anwender vor der Übernahme?
14. Welche fachlichen Validierungen und Pflichtfelder müssen eine Übernahme verhindern oder nur eine Warnung erzeugen?
15. Welche Dateigrößen, Objektzahlen und Laufzeiten sind realistisch?
16. Müssen Import und Export synchron im Browser laufen oder werden später Hintergrundjobs benötigt?
17. Welche Informationen müssen für Nachvollziehbarkeit, Undo/Redo, Versionshistorie und Support gespeichert werden?
18. Welche konkreten End-to-End-Beispiele und Fehlerfälle dienen als Abnahmekriterien?

Stelle Rückfragen in kleinen, zusammenhängenden Blöcken. Unterscheide in deinen Notizen ausdrücklich:

• vom Anwender bestätigte Anforderungen;
• sinnvolle Vorschläge;
• offene Entscheidungen;
• technische Folgerungen;
• bewusst nicht betrachtete spätere Ausbaustufen.

Erwartetes Ergebnis der Anforderungsrunde

Erstelle am Ende eine neue Arbeitsanweisung für das implementierende LLM. Sie soll mindestens enthalten:

• Ziel, Umfang und ausdrücklich ausgeschlossene Funktionen;
• vollständigen Anwenderworkflow für Erstimport, Zuordnung, Folgeimport und Rückexport;
• vereinbartes Dateiformat mit einem anonymisierten Beispiel;
• Feld- und Einheitenmapping einschließlich Richtung und Datenhoheit;
• Identitäts-, Matching- und Quellmodell;
• Regeln für neue, geänderte, fehlende und doppelte Objekte;
• Konflikt-, Validierungs- und Freigaberegeln;
• UI-Ablauf für Staging, Vorschau, Zuordnung und Bestätigung;
• Anforderungen an Revision, Atomarität, Undo/Redo und Audit;
• vorgeschlagene Modul- und Persistenzgrenzen, ohne bestehende Architekturregeln zu umgehen;
• schrittweise Implementierungsphasen mit überprüfbaren Abnahmekriterien;
• offene Punkte, die vor dem jeweiligen Implementierungsschritt geklärt werden müssen.

Die Arbeitsanweisung soll noch keinen Code enthalten. Sie muss klar markieren, welche Entscheidungen der Anwender tatsächlich getroffen hat und welche Teile nur Architekturvorschläge des LLM sind.

Weiterführende Projektdokumente

• AGENTS.md – verbindliche Domänen- und Implementierungsregeln
• docs/current-architecture.md – vollständiger aktueller Laufzeit- und Command-Pfad
• docs/project-history-and-external-model-architecture.md – bisherige Zukunftsrichtung für Versionierung, externes Modell und PostgreSQL
• docs/spec/01-domain-context.md – fachlicher Kontext
• docs/spec/03-data-model-concept.md – Datenmodellkonzept
• docs/spec/05-linked-devices-and-sync.md – Regeln für Projektgeräte und kontrollierte Synchronisierung
• docs/spec/07-implementation-phases-todo.md – Roadmap, insbesondere Phase 13
• docs/circuit-list-editor-known-limitations.md – noch nicht implementierte Funktionen