diff --git a/README.md b/README.md index 9ff7982..478d5b5 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,61 @@ -# Office-Addin-TaskPane-React +# Cable Consolidation (Excel Add-In) -This repository contains the source code used by the [Yo Office generator](https://github.com/OfficeDev/generator-office) when you create a new Office Add-in that appears in the task pane. You can also use this repository as a sample to base your own project from if you choose not to use the generator. +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". -## TypeScript +![SAT Elektrotechnik](https://kabel.casademm.de/assets/icon-80.png) -This template is written using [TypeScript](http://www.typescriptlang.org/). For the JavaScript version of this template, go to [Office-Addin-TaskPane-React-JS](https://github.com/OfficeDev/Office-Addin-TaskPane-React-JS). +## 📖 Inhaltsverzeichnis +- [Features](#-features) +- [Technologie-Stack](#-technologie-stack) +- [Dokumentation & Wiki](#-dokumentation--wiki) +- [Schnellstart](#-schnellstart) -## Debugging +--- -This template supports debugging using any of the following techniques: +## ✨ 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. -- [Use a browser's developer tools](https://learn.microsoft.com/office/dev/add-ins/testing/debug-add-ins-in-office-online) -- [Attach a debugger from the task pane](https://learn.microsoft.com/office/dev/add-ins/testing/attach-debugger-from-task-pane) -- [Use F12 developer tools on Windows 10](https://learn.microsoft.com/office/dev/add-ins/testing/debug-add-ins-using-f12-developer-tools-on-windows-10) +--- -## Questions and comments +## 💻 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. -We'd love to get your feedback about this sample. You can send your feedback to us in the *Issues* section of this repository. +--- -Questions about Office Add-ins development in general should be posted to [Microsoft Q&A](https://learn.microsoft.com/answers/questions/185087/questions-about-office-add-ins.html). If your question is about the Office JavaScript APIs, make sure it's tagged with [office-js-dev]. +## 📚 Dokumentation & Wiki -## Join the Microsoft 365 Developer Program +Alle ausführlichen Leitfäden und Dokumentationen findest du im Ordner [`/docs`](./docs): -Join the [Microsoft 365 Developer Program](https://aka.ms/m365devprogram) to get resources and information to help you build solutions for the Microsoft 365 platform, including recommendations tailored to your areas of interest. +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? -You might also qualify for a free developer subscription that's renewable for 90 days and comes configured with sample data; for details, see the [FAQ](https://learn.microsoft.com/office/developer-program/microsoft-365-developer-program-faq#who-qualifies-for-a-microsoft-365-e5-developer-subscription-). +--- -## Additional resources +## 🚀 Schnellstart -- [Office Add-ins documentation](https://learn.microsoft.com/office/dev/add-ins/overview/office-add-ins) -- More Office Add-ins samples at [OfficeDev on Github](https://github.com/officedev) +Wenn du direkt in den Code einsteigen willst: -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +```bash +# Abhängigkeiten installieren +npm install -## Copyright +# Lokalen Entwicklungs-Server starten & Excel Add-In Sideloaden +npm start -Copyright (c) 2021 Microsoft Corporation. All rights reserved. +# Produktions-Build erstellen +npm run build +``` + +*Entwickelt mit ❤️ für eine effizientere Kabelplanung.* diff --git a/docs/01_Architektur.md b/docs/01_Architektur.md new file mode 100644 index 0000000..d42cf28 --- /dev/null +++ b/docs/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/docs/02_Entwicklung_Setup.md b/docs/02_Entwicklung_Setup.md new file mode 100644 index 0000000..9334bc1 --- /dev/null +++ b/docs/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/docs/03_Benutzerhandbuch.md b/docs/03_Benutzerhandbuch.md new file mode 100644 index 0000000..b0ceb16 --- /dev/null +++ b/docs/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/docs/04_Deployment.md b/docs/04_Deployment.md new file mode 100644 index 0000000..75792da --- /dev/null +++ b/docs/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.)*