leistungsbilanz-ts/docs/spec/revit-excel-phase-14-plan.md

Phase 14 neu – Plan für die Linear-Excel-Anbindung

Verbindliche Fachgrundlage: Revit-Integration über Linear-Excel. Der alte CSV-Plan 14.0–14.6 ist abgelöst und wird nicht fortgeschrieben.

Status

Paket	Status	Ergebnis / Freigabepunkt
R0	abgeschlossen und freigegeben	Bestandsaudit, Zielmodell, Migration und Risiken; Freigabekorrekturen in R1 eingearbeitet.
R1	abgeschlossen	Anforderungen, Plan und Architektur auf Excel/Worksharing-ID umgestellt; alle Pflichtprüfungen bestanden.
R2	abgeschlossen und freigegeben	XLSX-Adapter, Parser, synthetische Fixtures, lokaler Referenzprüfer und reale Rückgabedatei sind erstellt; der korrigierte Rückimport wurde am 30.09.2026 erfolgreich in Linear getestet.
R3	abgeschlossen	Konfiguration ohne eigene Revision, Worksharing-ID-Datenmodell, Migration 0014, Snapshot 10, Transfer und Backend-CSV-Entfernung sind umgesetzt und geprüft.
R4	abgeschlossen	Revit-Seite, Navigation und revisionierte XLSX-Einstellungen mit Musterdateiprüfung sind umgesetzt; das alte Projektseitenmodal ist entfernt.
R5	abgeschlossen	Zustandslose XLSX-Vorschau, sechsstufiger Erstimportwizard und atomarer Importcommand mit parserfreiem Undo/Redo.
R6	abgeschlossen	Projektweite kompakte Objektliste, clientseitige Filter/Sortierung, Virtualisierung und revisionierte Sammeländerungen.
R7	abgeschlossen	Gruppierter Editorbereich, drei Drag-and-drop-Ziele, Row-Indikator, ausdrückliches Lösen und atomare Löschübergänge mit exaktem Undo/Redo.
R8	abgeschlossen	Rückgabe-Excel für alle, abweichende oder ausgewählte Objekte und append-only Exportnachweis sind umgesetzt.
R9	abgeschlossen	Vollständiger Folgeimport nach exakter Worksharing-ID mit Quellentscheidungen, fehlenden Objekten, bestätigtem Löschen und persistentem Undo/Redo.
R10	abgeschlossen	Ende-zu-Ende-Kette, 5.000-Objekte-Lasttest, gebatchte Zustandspersistenz und Abschlussdokumentation.
R11	abgeschlossen	Projekteinstellung maxSocketsPerCircuit und Geräteart-Merkmal isSocket samt Hochstufung und Einstellungs-UI.
R12	abgeschlossen	Reines Planungsmodul für Row-Bildung, Belegung, Konflikte und raumweise Aufteilung.
R13	abgeschlossen	Atomarer Command external-object.apply-assignment-plan mit Route und exakter Inverse.
R14	abgeschlossen	Zuordnungsdialog mit Drag-and-drop und Plan, Row-Objektliste mit Einzel-Lösen, Entfernen des R7-Drawers.

R0 – Audit

Ergebnis: R0-Audit. Die Freigabe vom 29.09.2026 enthält 13 Korrekturen. Bei Abweichungen zwischen dem historischen Audit und der aktuellen Anforderung gilt das neue Anforderungsdokument.

R1 – Dokumentation

Lieferumfang:

• neues verbindliches Excel-Anforderungsdokument;
• dieser R0–R10-Plan;
• alte CSV-Anforderungen und alter Plan als kurze Ablösungshinweise;
• LLM-Kontext auf die neue Quelle der Wahrheit kürzen;
• AGENTS.md, aktuelle Architektur, History-/External-Model-Architektur, Roadmap, README, Dokumentationsindex und bekannte Einschränkungen anpassen;
• reale Musterdatei per .gitignore vom Commit ausschließen;
• alle internen Links auf die neuen Dokumente umstellen.

Keine Laufzeit-, Schema- oder UI-Änderung. Abnahme: keine aktive Dokumentation nennt CSV/IfcGUID als künftigen Transport beziehungsweise Schlüssel; der aktuell noch vorhandene Legacy-Code bleibt als solcher klar benannt.

R2 – XLSX-Transportadapter

Dateien/Module: neues src/external-model/xlsx, synthetische Testfixtures und ein auf XLSX umgestellter Referenzprüfer mit Dateipfadargument. Eine neue direkte Bibliothek (exceljs, vorbehaltlich der Tests), keine DB-Änderung.

Abnahme:

• Kopfzeilenkommentare, Blattname, Spaltenbreiten, Formate und Zelltypen überleben einen strukturellen Roundtrip;
• erste Datenzeile/-spalte und Mappings funktionieren ohne separates layout.idColumn;
• Worksharing-ID/IfcGUID werden exakt und case-sensitiv behandelt;
• Zeile ohne ID und ohne Familie und Typ wird übersprungen, die Muster- Summenzeile B490 blockiert nicht;
• Zeile ohne ID mit Familie und Typ erzeugt Hinweis und wird übersprungen;
• maximal 10 MiB, nur .xlsx, Zeilen-/Spaltengrenzen nach dem Einlesen;
• keine Formelausführung;
• lokale Referenzprüfung bestätigt 487 Objekte und keine ID-Duplikate;
• aus der realen Musterdatei entsteht lokal eine nicht versionierte Rückgabedatei mit einigen geänderten Werten.

Danach stoppt die Arbeit. Der Nutzer testet diese Datei in Linear. Erst sein erfolgreicher Rückimport gibt R3 frei. Scheitert er, wird vor R3 ein konkreter OOXML-Patchadapter vorgeschlagen, der das Originalworkbook direkt ändert.

Implementierungsstand vom 30.09.2026: Der Adapter liegt unter src/external-model/xlsx, der Referenzprüfer unter scripts/verify-revit-reference-xlsx.ts. Er hat aus der lokalen Musterdatei die ignorierte Datei data/revit-reference/kbp-Stromkreis-R2-Rueckgabe.xlsx erzeugt. Die Datei enthält 487 Objektzeilen in Originalreihenfolge, keine Summenzeile und gezielte Änderungen an den ersten drei Objekten. Synthetische Tests decken Zelltypen, Zahlenformate, Formelergebnisse, Kommentare, Breiten, Auswahl, exakte ID-Vergleiche und Grenzen ab.

Für den Adapter ist exceljs@4.4.0 als direkte Abhängigkeit aufgenommen. Der Produktionsaudit meldet dafür ausschließlich uuid@8.3.2: Die gemeldete Schwachstelle betrifft die UUID-Funktionen v3/v5 mit übergebenem Puffer; ExcelJS verwendet die Abhängigkeit nur für UUID v4 bei erweiterten bedingten Formatierungen. Dieser Adapter ruft keine UUID-Funktion auf. Weitere gemeldete Auditbefunde gehören zu bereits vorhandenen Abhängigkeiten und werden nicht im fachlich begrenzten R2-Paket aktualisiert.

R3 – Datenmodell und Backend-Cutover

• Konfiguration ohne eigene Versionszählung;
• worksharing_id NOT NULL, Unique je Quelle; ifc_guid nullable ohne Unique;
• additive Migration nach vorherigem DB-Backup; alte externe Entwicklungsdaten verwerfen und Row-Mengen vorher auf manualQuantity zurücksetzen;
• Batch-Aufbewahrung: nur letzter Batch vollständig, ältere nur Metadaten;
• Snapshot 10, Restore und Transfer; alte CSV-Zustände/History klar ablehnen;
• Backend-CSV-Parser, Endpunkte und Verträge entfernen;
• Apply parst erneut; Undo/Redo verwenden ausschließlich gespeicherte Vorher-/Nachher-Zustände.

Risiken: Migration mit verknüpften Row-Mengen, alte History-Spitzen und vollständiges UUID-Remapping. Pflicht: echte SQLite-Commit-/Rollback-Tests.

R4 – Revit-Seite und Einstellungen

• Route /projects/:projectId/revit und Navigationseintrag;
• Status-/Aktionsgrundgerüst;
• Einstellungsmodal mit Musterdateierkennung, Layout und Feldzuordnung;
• Stromkreismodus combined | separate;
• Projektseiten-Button und revit-csv-modal.tsx entfernen;
• nur deutsche UI-Texte und bestehende Icon-/Kartenregeln.

R5 – Erstimport

• Vorschau und Plan mit erneuter Dateiübertragung beim Apply;
• Räume, Verteiler, Gerätearten, exakte Familienregeln und optionale ProjectDevices;
• fehlender GZF als sichtbarer Startwert 1, ohne Zusatzbestätigung;
• Warn-/Überspringregel für ID-lose Zeilen;
• ein atomarer Importcommand, keine Row-/Circuit-Erzeugung;
• Undo/Redo aus Commandzuständen ohne Workbook-Parsing.

Implementierungsstand vom 30.09.2026: Vorschau und Apply verwenden die projektweite XLSX-Konfiguration; Apply überträgt und parst die Datei erneut und vergleicht den SHA-256 der Vorschau. Der Wizard führt über Vorschau, Räume, Standardverteiler einschließlich Objekten ohne Raum, exakte Familienregeln, optionale ProjectDevices und Bestätigung. Unbekannte Familien können als Geräteart mit stabilen Client-UUIDs und sichtbarem GZF-Startwert 1 klassifiziert werden. external-model.apply-initial-import schreibt Konfiguration, Quelle, vollständigen letzten Batch, Raumzuordnungen und Objekte in einer Revision; alle circuitDeviceRowId bleiben null. Seine Inverse speichert beide Zustände vollständig, sodass Undo/Redo weder Datei noch Parser benötigen.

R6 – Objekttabelle und Sammelaktionen

• kompakte Objektliste einmal laden;
• clientseitig suchen, filtern und sortieren;
• virtualisierte Darstellung ohne Server-Pagination;
• stabile Mehrfachauswahl und Sammelaktionen für Verteiler, ProjectDevice und Objektplanungswerte;
• Standardverteileränderung wirkt nur auf unzugeordnete Objekte; verknüpfte Objekte folgen unverändert ihrer Row.

Implementierungsstand vom 30.09.2026: Der projektweite GET-Endpunkt liefert eine kompakte Liste ohne Batchbytes, Matrix oder Pagination. Die Revit-Seite sucht, filtert und sortiert vollständig im Client und rendert nur den sichtbaren Ausschnitt. Eine stabile Mehrfachauswahl ändert Verteiler, ProjectDevice, Leistung und GZF in einem persistenten external-object.update-planning-Command. Verknüpfte Objekte sind für diese Sammelaktionen gesperrt und folgen weiterhin ausschließlich ihrer Row.

R7 – Stromkreislisteneditor

• gruppierter rechter Revit-Bereich mit Anzahl-Badge;
• Drop auf Row, Circuit oder freien Bereich über vorhandene, angepasste Commands;
• Row-Indikator, Objektanzeige und Lösen mit Übernahme aktueller Row-Werte;
• Row-/Circuit-/Gruppen-Löschcommands lösen verknüpfte Objekte atomar und zeigen X Revit-Objekte werden wieder unzugeordnet;
• Undo stellt Objektlinks exakt wieder her;
• nur Raum-/Verteilerlöschung mit externen Referenzen bleibt gesperrt.

R8 – Rückgabe-Excel

• alle / abweichende / ausgewählte Objekte;
• zuletzt importiertes Workbook als strukturelle Grundlage;
• Stromkreisfelder des gewählten Modus sind Pflicht;
• fehlende optionale Bezeichnung-/Leistung-/Spannung-/Stromspalten nur als Hinweis überspringen;
• typisierte Zahlen, gemeinsame Export-/Abweichungsprojektion;
• append-only Exportnachweis ohne Projektrevision.

R8 baut auf der in R2 durch Linear bestätigten Transportstrategie auf.

Umsetzungsstand: Die Revit-Objekttabelle erzeugt die Rückgabe revisionssicher aus dem letzten vollständigen Import. Die gemeinsame Projektion berechnet Stromkreis, Bezeichnung, Leistung, Spannung und Strom; der XLSX-Adapter erhält Struktur und Formate und meldet fehlende optionale Spalten. Jeder erfolgreiche Download wird außerhalb von Projektcommands, Snapshots und Transfers mit Revision, Importbatch, Konfigurationskopie und Prüfsummen protokolliert.

R9 – Folgeimport

• exaktes, case-sensitives Matching nach Worksharing-ID;
• neu, geändert, unverändert, fehlend und Rückgabefeldabweichungen;
• Entscheidungen nur für fachliche Quelländerungen;
• akzeptierte Mengenänderungen und Row-Summen atomar;
• fehlende Objekte nicht automatisch lösen oder löschen;
• neuer letzter Vollbatch, vorheriger Batch auf Metadaten reduzieren;
• ein persistenter Undo-Schritt ohne Excel-Parsing bei Undo/Redo.

Umsetzungsstand vom 30.09.2026: Vorschau und Apply klassifizieren die vollständige XLSX nach exakter Worksharing-ID als neu, geändert, unverändert oder fehlend und weisen Rückgabefeldabweichungen getrennt aus. Der Wizard fordert Entscheidungen nur für fachliche Quelländerungen an. Apply überträgt und parst die Datei erneut, aktualisiert akzeptierte Mengen samt verknüpfter Row-Summe atomar und speichert den neuen Vollbatch; alle älteren Batches werden auf ihre Metadaten reduziert. Fehlende Objekte behalten zunächst Link und Menge. Eine gesondert bestätigte Aktion kann sie anschließend mit passender Row-Mengenänderung löschen. Beide Commands besitzen vollständige Inversen; Undo/Redo liest keine XLSX-Datei.

R10 – Härtung

Ende-zu-Ende-Test:

Import → Objektplanung → Row-Zuordnung → Rückgabe → Folgeimport
       → Snapshot/Restore → Projektduplikat → Undo/Redo nach Neustart

Zusätzlich: mehrere Tausend synthetische Objekte, virtualisierte UI, Speicher-/Payload-/Transaktionsmessungen, Löschwarnungen samt Link-Inversen, alte CSV-Ablehnungen und Dokumentation auf den ausgelieferten Stand.

Umsetzungsstand vom 30.09.2026: Der dateibasierte Integrationstest deckt die vollständige Kette bis zu Undo/Redo nach einem Datenbankneustart ab. Ein synthetisches Workbook mit 5.000 Objekten durchläuft Erst- und Folgeimport, Snapshot-Restore, Projektduplikat sowie die extrahierte Clientfilter- und Virtualisierungslogik. Die dabei gefundene SQLite-Grenze ungebatchter Inserts ist für alle vollständigen External-Model-Zustandspfade behoben. Messwerte und Abnahme stehen in R10-Abnahme. Phase 14 ist damit abgeschlossen.

R11–R14 – Zuordnungsdialog und Steckdosen-Höchstwert

Fachgrundlage: Abschnitte 5, 6 und 11 der Anforderungen, Stand 30.10.2026. Anlass: Der R7-Drawer kann gleichartige Objekte eines Raums nur gesamt oder einzeln zuordnen. Steckdosen müssen objektweise und unter einem auftraggeberabhängigen Höchstwert auf mehrere Stromkreise verteilt werden.

R11 – Einstellungen

• Projekteinstellung maxSocketsPerCircuit: Migration 0018 (nullable Spalte), project.update-settings Schema-Version 4 (1–3 bleiben ausführbar und lassen den Wert unverändert), Snapshot-Schema 11 (1–10 mit null hochgestuft), Projekttransfer, PUT-Route und Projekteinstellungsdialog;
• ExternalModelConfiguration Schema-Version 2 mit deviceTypes[].isSocket; Version 1 wird beim Lesen aus den socketCount-Regeln hochgestuft (gespeicherte Konfiguration, Importbatch-Kopien, History-Commands, Snapshots, Transfer);
• Revit-Einstellungen: Merkmal „Steckdose“ je Geräteart; Wizards belegen es vor.

R12 – Planungsmodul

• reines, importfreies Modul für Client und Server;
• Row-Bildung im Zielstromkreis, Belegung je Stromkreis, Konfliktliste, Kategorieprüfung und raumweise Aufteilung nach Anforderung 11.6;
• fokussierte Unit-Tests, u. a.: 8 Doppelsteckdosen bei Grenze 8 ergeben zwei Stromkreise mit je 4 Objekten; Räume werden nur bei Bedarf geteilt; ein Einzelobjekt über der Grenze erhält einen eigenen Stromkreis.

R13 – Command

• external-object.apply-assignment-plan über die gemeinsame Project-Command-Transaktionsgrenze und external-object-assignment.persistence.ts;
• serverseitige Neuprüfung mit dem R12-Modul; Konflikte und Überschreitungen nur mit ausdrücklich gelisteter Bestätigung;
• strikte zod-Eingabe, Routentests (nicht angemeldet, fremdes Objekt, ungültige Eingabe), SQLite-Commit/Rollback, Undo/Redo nach Neustart.

R14 – Editor-UI

• Zuordnungsdialog nach Anforderung 11.2–11.7 mit lokalem Plan, Drag-and-drop, Tastaturalternative, Prüfansicht und 409-Neuprüfung;
• Kontextmenü-Einstieg mit vorausgewähltem Ziel;
• Row-Badge öffnet die Objektliste mit Einzel- und Gesamt-Lösen;
• R7-Drawer und Grid-Drop für Revit-Objekte entfernen; AGENTS.md und Architekturdokumentation nachziehen.

Pflichtprüfungen je Paket R1–R14

fokussierte Tests
npm test
npm run build:api
npm run build:web
npm run typecheck:scripts
npx tsc --noEmit -p tsconfig.next.json

Jedes Paket wird mit einer knappen imperativen Commit-Message abgeschlossen.