Add Revit requirements handoff

2026-07-29 19:26:39 +02:00
parent fac6c9350f
commit cfd4778305
2 changed files with 270 additions and 0 deletions
@@ -27,6 +27,7 @@ ausdrücklich getrennt und dürfen nicht als bereits implementiert verstanden we
 ## Zukunftsarchitektur

 - [Projektversionen und externer Modellaustausch](project-history-and-external-model-architecture.md)
+- [LLM-Kontext für die Revit-Anforderungsplanung](revit-requirements-llm-context.md)
 - [Zukünftige Dimensionierung](spec/06-future-sizing-and-calculations.md)
 - [Roadmap und Phasen](spec/07-implementation-phases-todo.md)
 - [Aktueller Produkt-Backlog](spec/08-current-product-backlog.md)
@@ -0,0 +1,269 @@
+# 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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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