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