Document Linear Excel integration

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

@@ -0,0 +1,173 @@
+# Phase 14 neu – Plan für die Linear-Excel-Anbindung
+
+Verbindliche Fachgrundlage:
+[Revit-Integration über Linear-Excel](revit-excel-integration-requirements.md).
+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 | offen | XLSX-Adapter, Parser, synthetische Fixtures, lokaler Referenzprüfer und reale Rückgabedatei. Danach zwingende Linear-Abnahme durch den Nutzer. |
+| 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](revit-excel-r0-audit.md). 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.
+
+## 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:
+
+```text
+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
+
+```text
+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.