diff --git a/docs/README.md b/docs/README.md index e19ece3..b7b8409 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/revit-requirements-llm-context.md b/docs/revit-requirements-llm-context.md new file mode 100644 index 0000000..060517d --- /dev/null +++ b/docs/revit-requirements-llm-context.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