forked from jappel/leistungsbilanz-ts
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# 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 | 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. |
|
||
|
||
## 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.
|
||
|
||
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:
|
||
|
||
```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.
|
||
|
||
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](revit-excel-r10-validation.md). Phase 14 ist
|
||
damit abgeschlossen.
|
||
|
||
## 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.
|