docs: Add root README and Wiki documentation structure

This commit is contained in:
Toni Martin
2026-02-25 13:27:37 +01:00
parent ca0022e250
commit ac1f39f16c
5 changed files with 311 additions and 21 deletions

View File

@@ -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.*

40
docs/01_Architektur.md Normal file
View File

@@ -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.

View File

@@ -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.

View File

@@ -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.

130
docs/04_Deployment.md Normal file
View File

@@ -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.)*