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	offen	Vollständiger Folgeimport nach Worksharing-ID.
R10	offen	Ende-zu-Ende-Härtung, große Datenmengen und Abschlussdokumentation.

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.

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.

Pflichtprüfungen je Paket R1–R10

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.