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	implementiert, Linear-Abnahme ausstehend	XLSX-Adapter, Parser, synthetische Fixtures, lokaler Referenzprüfer und reale Rückgabedatei sind erstellt. R3 bleibt bis zum erfolgreichen Linear-Test gesperrt.
R3	gesperrt bis R2-Abnahme	Konfiguration, Identität, Migration, Snapshot 10, Transfer und Backend-CSV-Entfernung.
R4	offen	Revit-Seite, Navigation, Einstellungen, altes Projektseitenmodal entfernen.
R5	offen	Erstimportwizard mit Gerätearten, Familienregeln und optionalen ProjectDevices.
R6	offen	Virtualisierte Objekttabelle und Sammelzuordnungen.
R7	offen	Editorbereich, Gruppierung, Drag-and-drop, Lösen und integrierte Löschübergänge.
R8	offen	Rückgabe-Excel und append-only Exportnachweis.
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.

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.

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.

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.