Skip to content

Architektur & Geschäftslogik

Dieses Dokument bietet einen technischen Überblick über den Aufbau des Cable Consolidation Add-Ins.

1. Projektstruktur

Das Projekt ist ein klassisches Web-Projekt, welches über eine manifest.xml an Excel angebunden wird. Die UI läuft im "Task Pane" (Seitenleiste) von Excel.

Der relevante Code befindet sich hauptsächlich im Ordner src/taskpane/:

  • components/: Enthält alle React-Komponenten.
  • App.tsx: Die Hauptkomponente, steuert den Wizard-Flow (Auswahl -> Mapping -> Fertig) und den globalen State.
  • SheetSelector.tsx: Handhabt die Auswahl interner Blätter und den File-Upload (via FileReader und SheetJS) für externe Dateien.
  • ColumnMapper.tsx: Erlaubt dem Nutzer die Überprüfung des durch das Tool vorgeschlagenen Spalten-Mappings.
  • models.ts: Definiert TypeScript-Interfaces (SheetInfo, TargetColumnDef) und die Alias-Wörterbücher für das Smart Mapping.
  • excelLogic.ts: Das Herzstück für die Datenverarbeitung. Hier passiert die Magie zwischen dem Add-In und dem eigentlichen Excel-Dokument via Office.js.

2. Core Business Logic (excelLogic.ts)

getAvailableSheets()

Liest mittels Office.js API (context.workbook.worksheets) alle Tabellenblätter aus der aktuellen Mappe aus. Versteckte Blätter und das Blatt "Kabelliste" (die Ausgabe) werden übersprungen.

detectHeadersAndColumns()

Der Kern für die intelligente Spaltenerkennung. 1. Liest entweder über Office.js (intern) oder über SheetJS (extern) die ersten 50 Zeilen ein. 2. Es vergleicht alle Zellen-Strings in Kleinbuchstaben mit den in models.ts definierten Aliases (TargetColumnDef). 3. Die Zeile, in der die meisten Treffer landen, wird als Kopfzeile (Header-Row) festgelegt. Aus dieser Zeile wird das automatisierte Spalten-Mapping für den nächsten Installationsschritt abgeleitet.

consolidateData()

Der wichtigste Part: 1. Iteriert über alle vom Nutzer verifizierten Blätter. 2. Holt die Rohdaten. (Bei Office.js: getUsedRange().text, um korrekte Datums-Formatierungen zu erhalten anstatt unroher Date-Serials). 3. Fügt die Zellen so zusammen, dass sie exakt in die Zielstruktur (TARGET_COLUMNS + Zusatzspalten "Länge", "gezogen am", "von (Monteur)") passen. 4. Leere Zeilen werden übersprungen. 5. In Excel wird ein neues Worksheet "Kabelliste" angelegt, die Daten gesammelt hereingeschrieben und das Ganze schließlich als Formatierte Tabelle (TableStyleLight9) gepinnt. Die Ranges werden zudem mit @ formatiert, um unerwünschtes Number-Parsing seitens Excel zu verhindern.

3. Web-Technologien

  • React: Modernes State-Management (useState, useEffect). UI Updates basierend auf "Wizard Steps" (select_sheets => map_columns => done).
  • Fluent UI: @fluentui/react-components (die aktuellste Version 9) sorgt dafür, dass sich Buttons, Checkboxen, Accordions und Spinner zu 100% nativ wie Microsoft Office anfühlen.
  • SheetJS (xlsx): Wird genutzt, um hochgeladene, externe Excel-Files komplett lokal (!) im Browser des Nutzers in JSON- bzw. 2D-Arrays umzuwandeln, ohne sie an einen Zwischenserver schicken zu müssen.