diff --git a/01_Architektur.md b/01_Architektur.md new file mode 100644 index 0000000..d42cf28 --- /dev/null +++ b/01_Architektur.md @@ -0,0 +1,40 @@ +# 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. diff --git a/02_Entwicklung_Setup.md b/02_Entwicklung_Setup.md new file mode 100644 index 0000000..9334bc1 --- /dev/null +++ b/02_Entwicklung_Setup.md @@ -0,0 +1,46 @@ +# Entwickler-Setup & Guideline + +Wenn du weitere Features zum Cable Consolidation Add-In hinzufügen möchtest, hilft dir dieses Dokument beim lokalen Setup. + +## 1. Lokale Entwicklungsumgebung + +**Voraussetzungen:** +- Node.js (>= 16.x) +- `npm` (wird mit Node.js installiert) +- Microsoft Excel Desktop-App (für Windows/Mac) oder Office 365 Web + +**Installation:** +```bash +git clone https://gitea.casademm.de/Peacock/Cable-consolidation.git +cd Cable-consolidation +npm install +``` + +## 2. Den Entwicklungs-Server starten + +Um Änderungen lokal zu testen, führe aus: +```bash +npm start +``` + +**Was passiert dabei?** +1. Der Befehl startet einen lokalen HTTPS-Webserver (webpack-dev-server) auf Port `3037` (oder wie in der `webpack.config.js` angegeben). +2. Es führt im Hintergrund (wenn auf Windows) ein Skript aus, das die `manifest.xml` an dein lokales Excel Desktop "sideloadet". +3. Deine Excel App öffnet sich automatisch. Du findest den Add-In Button unter "Start" (Ganz rechts). +4. Wenn du Code-Dateien (.tsx, .ts, .css) speicherst, wird das Add-In im Aufgabenbereich dank "Hot Module Replacement" sofort automatisch neu geladen. + +## 3. Typische Fehler & Lösungen + +* **Zertifikatsfehler im Browser:** Web-Add-Ins erfordern zwingend HTTPS. Falls der Dev-Server meckert, dass kein Zertifikat vorhanden ist, führe aus: + `npx office-addin-dev-certs install` +* **CORS-Probleme bei externen Requests:** Solange ihr alles komplett im Frontend macht (wie beim SheetJS-Upload), gibt es keine CORS Probleme. Falls ihr künftig aber APIs vom Firmen-Backend abfragen wollt, müsst ihr an Nginx (bzw. dem Backend) entsprechende `Access-Control-Allow-Origin` Header setzen. + +## 4. Für die Produktion bauen + +Wenn du ein neues Feature fertiggestellt hast, musst du das Projekt bauen, um minifizierte, optimierte JavaScript-Bundles zu erhalten: + +```bash +npm run build +``` + +Das Ergebnis liegt anschließend im Ordner `/dist`. Die dortigen Dateien müssen dann einfach auf den Produktions-Server (`kabel.casademm.de`) hochgeladen und dort überschrieben werden. diff --git a/03_Benutzerhandbuch.md b/03_Benutzerhandbuch.md new file mode 100644 index 0000000..b0ceb16 --- /dev/null +++ b/03_Benutzerhandbuch.md @@ -0,0 +1,51 @@ +# Kurzanleitung: Kabel-Konsolidierungs Add-In + +Willkommen beim Kabel-Konsolidierungs Tool! Mit diesem Add-In kannst du schnell und effizient hunderte von Kabel-Einträgen aus verschiedenen Arbeitsblättern zu einer einzigen "Kabelliste" zusammenfassen. + +## So startest du das Tool + +1. Öffne Excel. +2. Wechsle im oberen Menüband (Ribbon) auf den Reiter **Start**. +3. Klicke ganz rechts auf den neuen Button **Start Konsolidierung** (mit dem Kabel-Symbol). +4. Das Add-In öffnet sich daraufhin am rechten Bildschirmrand. + +--- + +## 1. Blätter auswählen & Dateien hochladen + +Im ersten Schritt sagst du dem Add-In, *woher* es die Kabeldaten nehmen soll: + +* **Interne Blätter:** Hier ist eine Liste aller sichtbaren Arbeitsblätter deines aktuell geöffneten Excel-Dokuments. Hake einfach alle Blätter an, die Kabeldaten enthalten. +* **Externe Excel-Dateien hinzufügen:** Wenn deine Kollegen dir weitere Excel-Listen (als `.xlsx`, `.xlsm` oder `.csv`) geschickt haben, musst du diese **nicht** manuell in deine aktuelle Mappe kopieren! Klicke einfach auf den Durchsuchen-Button und lade die Dateien direkt hoch. Das Add-In liest sie im Hintergrund aus und fügt auch diese Arbeitsblätter der Checkliste hinzu. + +Klicke auf `Weiter`, wenn du alle gewünschten Blätter markiert hast. + +--- + +## 2. Spalten-Mapping (Das Herzstück!) + +Nun liest das Tool automatisch die ersten 50 Zeilen der gewählten Blätter aus und sucht nach den Kopfzeilen (Spaltennamen), die Kabel-Informationen beinhalten. + +Das Add-In ist "schlau" und erkennt auch Abweichungen (es weiß z.B., dass "Kabelnummer" und "Nr." dasselbe meinen wie "K-Nr."). + +* **Ein grünes "OK":** Das Tool hat alle nötigen Spalten für dieses Arbeitsblatt automatisch gefunden. Du musst hier nichts mehr tun. +* **Eine rote Warnung "X Lücken":** Für dieses Blatt konnten nicht alle Spalten automatisch gefunden werden. + * Klicke auf das Blatt, um die Details auszuklappen. + * Stelle sicher, dass unter **"Kopfzeile (Index 0-basiert)"** die korrekte Zeile angegeben ist, in der die Spaltenüberschriften stehen. Wenn deine Überschriften in Zeile 5 stehen, trage hier die "4" ein (da die Zählung bei 0 beginnt). + * Weise dann über das Dropdown-Menü manuell zu, welche Spalte im Dokument unserer Zielspalte (z.B. "von Raum") entspricht. + * Wenn ein Blatt komplett leer ist oder versehentlich ausgewählt wurde, lass die Spalten auf "--- Nicht gefunden ---". Das Tool überspringt diese Einträge am Ende ganz einfach, anstatt kaputtzugehen. + +--- + +## 3. Konsolidierung + +Sobald du zufrieden bist, klicke unten auf den blauen Button **"Konsolidieren"**. + +Das Add-In wird nun: +1. Eine komplett neue Tabelle namens **"Kabelliste"** in deiner Arbeitsmappe erzeugen (bzw. eine alte überschreiben). +2. Alle Daten aus den internen UND externen Blättern in diese Tabelle schütten. +3. Die Tabelle schön und übersichtlich formatieren (inkl. Filter-Buttons). +4. Leere Zeilen automatisch überspringen und leere Spalten sauber auffüllen. + +Fertig! Dir wird am Ende rechts angezeigt, wie viele Zeilen erfolgreich aus den Blättern konsolidiert wurden. +Du kannst das Add-In nun schließen oder einen neuen Durchlauf starten. diff --git a/04_Deployment.md b/04_Deployment.md new file mode 100644 index 0000000..75792da --- /dev/null +++ b/04_Deployment.md @@ -0,0 +1,130 @@ +# Deployment Guide: Ubuntu Server (Nginx + SSL) + +Diese Anleitung beschreibt, wie du das fertig gebaute Excel Add-in auf deinem privaten Ubuntu-Server unter der Domain `https://kabel.casademm.de` hosten kannst. + +## Voraussetzung +1. Ein Linux-Server (Ubuntu) mit Root/Sudo-Zugriff. +2. Die Domain `kabel.casademm.de` muss im DNS-Manager deines Domain-Anbieters auf die IP-Adresse (A-Record) dieses Servers zeigen. +3. Du hast lokal auf deinem Entwicklungsrechner den Befehl `npm run build` ausgeführt. Dadurch wurde ein Ordner namens `dist` in deinem Projektverzeichnis (`C:\EWSL_Add_in\CableConsolidation\dist`) erstellt. + +--- + +## Schritt 1: Nginx installieren +Verbinde dich per SSH mit deinem Ubuntu-Server und aktualisiere die Paketquellen, um danach den Nginx Webserver zu installieren: + +```bash +sudo apt update +sudo apt install nginx -y +``` + +Stelle sicher, dass Nginx läuft und beim Systemstart automatisch mitstartet: +```bash +sudo systemctl enable nginx +sudo systemctl start nginx +``` + +Falls du die `ufw` Firewall nutzt, erlaube den Nginx-Traffic: +```bash +sudo ufw allow 'Nginx Full' +``` + +--- + +## Schritt 2: Dateien auf den Server kopieren + +1. Erstelle auf dem Server ein Verzeichnis für deine Domain: +```bash +sudo mkdir -p /var/www/kabel.casademm.de/html +``` + +2. Passe die Rechte an, damit Nginx (und dein User) darauf zugreifen können: +```bash +sudo chown -R $USER:$USER /var/www/kabel.casademm.de/html +sudo chmod -R 755 /var/www/kabel.casademm.de +``` + +3. Übertrage nun den Inhalt deines lokalen `dist`-Ordners in dieses Verzeichnis auf dem Server. Das kannst du z.B. über ein SFTP-Programm wie WinSCP oder FileZilla machen. + * **Quelle:** `C:\EWSL_Add_in\CableConsolidation\dist\*` + * **Ziel (Server):** `/var/www/kabel.casademm.de/html/` + +*(Tipp: Vergewissere dich, dass die Datei `taskpane.html` und der `assets`-Ordner direkt im `/html/`-Verzeichnis liegen!)* + +--- + +## Schritt 3: Nginx für die Domain konfigurieren + +Erstelle eine neue Server-Block Konfigurationsdatei für Nginx: + +```bash +sudo nano /etc/nginx/sites-available/kabel.casademm.de +``` + +Kopiere folgenden Inhalt hinein (dies lauscht erstmal nur auf Port 80): + +```nginx +server { + listen 80; + listen [::]:80; + + root /var/www/kabel.casademm.de/html; + index taskpane.html index.html index.htm; + + server_name kabel.casademm.de; + + location / { + try_files $uri $uri/ =404; + # Erlaubt CORS, was für Web-Add-Ins nützlich ist + add_header Access-Control-Allow-Origin *; + } +} +``` + +Speichere die Datei (in Nano: `Strg+O`, `Enter`, `Strg+X`). + +Aktiviere die Konfiguration, indem du einen Symlink erstellst: +```bash +sudo ln -s /etc/nginx/sites-available/kabel.casademm.de /etc/nginx/sites-enabled/ +``` + +Prüfe, ob Nginx meckert, und starte neu: +```bash +sudo nginx -t +sudo systemctl reload nginx +``` + +--- + +## Schritt 4: SSL-Zertifikat sichern (WICHTIG!) +Microsoft Office weigert sich strikt, Add-ins ohne gültiges HTTPS-Zertifikat zu laden. Wir nutzen Certbot für ein kostenloses Let's Encrypt Zertifikat. + +1. Installiere Certbot: +```bash +sudo apt install certbot python3-certbot-nginx -y +``` + +2. Generiere das Zertifikat: +```bash +sudo certbot --nginx -d kabel.casademm.de +``` + +Certbot wird dich nach deiner E-Mail-Adresse fragen und dir anbieten, den Traffic automatisch auf HTTPS umzuleiten (wähle Option "2: Redirect"). + +Sobald Certbot fertig ist, läuft dein Server sicher unter `https://kabel.casademm.de`. + +--- + +## Schritt 5: In Excel einbinden / ausrollen + +Jetzt wo dein Server online ist, benötigst du (und deine Firma) nur noch eine einzige Datei: Die `manifest.xml`. + +In der `manifest.xml` (welche du ebenfalls in deinem Projekt-Root hast) stehen bereits alle Verweise auf `https://kabel.casademm.de`. + +**Wie lade ich es im Office 365 Admin Center hoch?** +1. Die IT geht auf `admin.microsoft.com`. +2. Gehe zu **Einstellungen > Integrierte Apps**. +3. Klicke auf **Benutzerdefinierte Apps hochladen**. +4. Lade die finale `manifest.xml` hoch. +5. Weise die App den entsprechenden Benutzern (oder allen) zu. +6. Sobald Excel von den Mitarbeitern neugestartet wird, erscheint der neue Button im Menüband! + +*(Für lokale Tests kannst du das Add-In in Excel auch einfach über "Meine Add-ins" > "Zusatz-Add-In hochladen" nutzen.)* diff --git a/05_Lokales_Prod_Sideloading.md b/05_Lokales_Prod_Sideloading.md new file mode 100644 index 0000000..4da2ef6 --- /dev/null +++ b/05_Lokales_Prod_Sideloading.md @@ -0,0 +1,54 @@ +# Lokales Testen des Produktions-Add-Ins (Sideloading) + +Wenn der lokale Entwicklungs-Server (`npm start`) nicht läuft, kann das Produktions-Add-In (welches auf dem Live-Server gehostet wird) nicht einfach in der Excel Desktop-App über das Microsoft Admin-Center "hochgeladen" werden. +Um die Produktions-Version (`manifest.prod.xml`) dauerhaft lokal in Excel zu installieren, nutzt man unter Windows einen **freigegebenen Netzwerkordner (Shared Folder)**. + +Folge dieser Schritt-für-Schritt-Anleitung, um dein lokales Excel für das Produktions-Add-In einzurichten: + +## 1. Vorbereitung des Produktions-Manifests + +1. Stelle sicher, dass du eine tagesaktuelle Version der `manifest.prod.xml` hast. Du kannst diese unter anderem **direkt aus dem entwickelten Add-In herunterladen**, wenn du es lokal laufen hast (Link unten im Add-In: *Prod-Manifest (.xml)*). +2. Diese Datei enthält die echten Produktions-URLs statt der `localhost`-Adressen. + +*(Optional: Wenn du Dev- und Prod-Add-In gleichzeitig in Excel nutzen möchtest, stelle sicher, dass die `` in der `manifest.prod.xml` von der ID in der normalen `manifest.xml` abweicht.)* + +## 2. Einen lokalen Ordner freigeben (Shared Folder) + +Excel Desktop benötigt zwingend einen Netzwerkpfad (Share), um Manifeste lokal zu finden. + +1. Erstelle irgendwo auf deinem PC einen neuen Ordner, z. B. `C:\ExcelManifests`. +2. Lege deine heruntergeladene `manifest.prod.xml` in diesen Ordner. +3. Klicke im Windows Explorer mit der **rechten Maustaste** auf den Ordner -> **Eigenschaften**. +4. Gehe zum Reiter **Freigabe** und klicke auf **Erweiterte Freigabe...**. +5. Setze den Haken bei **Diesen Ordner freigeben**. Merke dir den Freigabenamen (meist der Ordnername, z.B. `ExcelManifests`). +6. Klicke auf **OK** und schließe die Eigenschaften. Du solltest nun den Netzwerkpfad sehen (z. B. `\\DeinPCName\ExcelManifests` oder `\\localhost\ExcelManifests`). + +## 3. Den Ordner in Excel als "Trusted Catalog" hinzufügen + +Damit Excel diesen freigegebenen Ordner nach Manifesten durchsucht: + +1. Öffne ein beliebiges lokales **Excel**. +2. Gehe auf **Datei** -> **Optionen** -> **Trust Center** (bzw. Sicherheitscenter). +3. Klicke auf den Button **Einstellungen für das Trust Center...**. +4. Wähle im linken Menü **Vertrauenswürdige Add-In-Kataloge** aus. +5. Trage unten bei **Katalog-URL** den Netzwerkpfad aus Schritt 2 ein (z. B. `\\localhost\ExcelManifests`). +6. Klicke auf **Katalog hinzufügen**. +7. **WICHTIG:** Setze den Haken bei **Im Menü anzeigen** (Show in Menu) für diesen neuen Eintrag! +8. Klicke auf **OK** und **starte Excel komplett neu**. + +## 4. Das Produktions-Add-in in Excel laden + +Nach dem Neustart von Excel: + +1. Gehe im Menüband auf den Reiter **Einfügen** -> **Add-Ins abrufen** (Get Add-ins). +2. Oben im erscheinenden Dialogfenster siehst du nun einen neuen Reiter namens **FREIGEGEBENER ORDNER** (Shared Folder). +3. Klicke darauf. Dort taucht nun dein Produktions-Add-in auf. +4. Klicke auf **Hinzufügen**. + +**Das war's!** +Ab sofort kannst du dein Produktions-Add-in ganz normal über das Menü starten, auch wenn dein lokaler Entwicklungs-Server aus ist. + +### Updates des Add-Ins +Da die Excel Desktop-App bei jedem Start des Add-Ins die aktuellsten React/Web-Dateien von deinem Server lädt, musst du diesen Prozess **nicht** bei jedem Update wiederholen. + +Du musst die `manifest.prod.xml` im Ordner `C:\ExcelManifests` nur dann aktualisieren (überschreiben) und das Add-In neu in Excel laden, wenn sich grundlegende Metadaten im Manifest ändern (wie z. B. der Name des Add-Ins, die URL, Icons oder angeforderte Berechtigungen). diff --git a/Home.md b/Home.md index ea78fbf..53a6f11 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,62 @@ -Willkommen im Wiki. \ No newline at end of file +# Cable Consolidation (Excel Add-In) + +Ein **Microsoft Excel Web-Add-In**, entwickelt von der SAT Elektrotechnik GmbH, zur intelligenten und effizienten Zusammenführung von Kabeldaten aus verschiedenen Tabellenblättern in eine formatierte "Kabelliste". + +![SAT Elektrotechnik](https://kabel.casademm.de/assets/icon-80.png) + +## 📖 Inhaltsverzeichnis +- [Features](#-features) +- [Technologie-Stack](#-technologie-stack) +- [Dokumentation & Wiki](#-dokumentation--wiki) +- [Schnellstart](#-schnellstart) + +--- + +## ✨ Features +Das Add-In optimiert den Planungsprozess durch folgende Funktionen: +- **Interne & Externe Quellen:** Konsolidiert Tabellenblätter aus der *aktuell geöffneten* Arbeitsmappe sowie aus *extern hochgeladenen* Excel-Dateien (`.xlsx`, `.xlsm`, `.csv`). +- **Intelligentes Mapping (Smart Aliasing):** Erkennt selbstständig die benötigten Spalten (z.B. "K-Nr.", "von", "nach Raum", etc.), auch wenn alternative Bezeichnungen (wie "Kabelnummer" oder "Nr.") verwendet werden. +- **Fehlertoleranz:** Leere Blätter, versteckte Blätter oder fehlende Kopfzeilen bringen das Add-In nicht zum Absturz. Der Benutzer kann fehlende Zuweisungen manuell vornehmen. +- **Saubere Ausgabe:** Die konsolidierten Daten werden automatisch als ansprechende, filterbare Excel-Tabelle generiert. + +--- + +## 💻 Technologie-Stack +Das Projekt nutzt modernste Web-Technologien in Kombination mit Microsofts Add-In Architektur: +- **React (v18)** für die dynamische Benutzeroberfläche (Task Pane). +- **TypeScript** für typsichere Geschäftslogik. +- **Fluent UI (v9)** für ein nahtloses, Microsoft-natives Design. +- **Office.js API** zum direkten Lesen und Schreiben im Excel-Dokument. +- **SheetJS (xlsx)** zum clientseitigen Parsen von externen Dateien direkt im Browser-Speicher. +- **Webpack** als Build-Tool. + +--- + +## 📚 Dokumentation & Wiki + +Alle ausführlichen Leitfäden und Dokumentationen findest du im Ordner [`/docs`](./docs): + +1. **[Architektur & Logik](./docs/01_Architektur.md)**: Erklärungen zur Code-Basis, den React-Komponenten und der Office.js Integration. +2. **[Entwickler-Setup](./docs/02_Entwicklung_Setup.md)**: Wie setze ich das Projekt lokal auf und entwickle weiter? +3. **[Benutzerhandbuch](./docs/03_Benutzerhandbuch.md)**: Die Schritt-für-Schritt Anleitung für die Endnutzer. +4. **[Deployment & Hosting](./docs/04_Deployment.md)**: Wie kommt das Tool auf den Ubuntu-Server und in das M365 Admin Center? +5. **[Lokales Prod-Add-In (Sideloading)](./docs/05_Lokales_Prod_Sideloading.md)**: Wie lade ich das Produktions-Add-in in meiner lokalen Excel-App, wenn der Dev-Server nicht läuft? + +--- + +## 🚀 Schnellstart + +Wenn du direkt in den Code einsteigen willst: + +```bash +# Abhängigkeiten installieren +npm install + +# Lokalen Entwicklungs-Server starten & Excel Add-In Sideloaden +npm start + +# Produktions-Build erstellen +npm run build +``` + +*Entwickelt mit ❤️ für eine effizientere Kabelplanung.* diff --git a/README.md b/README.md new file mode 100644 index 0000000..9ac0d11 Binary files /dev/null and b/README.md differ