# Starface Kontakt-Sync - Outlook Add-in

Outlook Add-in zur bidirektionalen Synchronisation von Kontakten zwischen Microsoft Outlook und einer Starface Telefonanlage.

## Funktionen

- **Bidirektionale Synchronisation** von Kontakten zwischen Outlook und Starface
- **Profil-System** zum Verwalten mehrerer Sync-Konfigurationen (z.B. verschiedene Adressbücher oder Anlagen)
- **Starface-Adressbücher**: Zentrales Adressbuch, persönliches Adressbuch und Tag-basierte Adressbücher
- **Outlook-Kontaktordner**: Frei wählbarer Kontaktordner als Sync-Ziel
- **Sync-Richtung** konfigurierbar: Outlook → Starface, Starface → Outlook oder bidirektional
- **Intelligentes Matching**: Kontakte werden anhand von E-Mail-Adresse oder Name abgeglichen
- **Änderungserkennung**: Nur geänderte Kontakte werden übertragen (Hash-basiert)
- **Kompatibel** mit Outlook Classic und dem neuen Outlook (Office Web Add-in)
- **Einfacher Installer** mit automatischer Zertifikatskonfiguration

## Voraussetzungen

- [Node.js](https://nodejs.org/) ab Version 18 (LTS empfohlen)
- npm (wird mit Node.js mitgeliefert)
- Microsoft Outlook (Classic oder Neu)
- Starface Telefonanlage ab Version 6.7 (REST-API)
- Windows 10/11 (für den Installer)

## Installation beim Kunden

### Schnellinstallation (empfohlen)

Der Installer richtet alles automatisch ein: Zertifikate, lokaler Webserver, Outlook-Registrierung.

**Schritt 1: Add-in bauen (einmalig, auf dem Entwickler-PC)**

```bash
npm install
npm run build
```

**Schritt 2: Installer-Paket zum Kunden mitnehmen**

Folgende Dateien/Ordner werden benötigt:

```
installer/
├── setup.ps1           # Installations-Script
├── uninstall.ps1       # Deinstallations-Script
├── local-server.js     # Lokaler HTTPS-Webserver
dist/                   # Build-Ausgabe (von Schritt 1)
```

**Schritt 3: Beim Kunden ausführen (als Administrator)**

```powershell
# PowerShell als Administrator öffnen, dann:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\installer\setup.ps1
```

Das Setup fragt interaktiv ab:

| Abfrage | Beispiel | Beschreibung |
|---------|----------|--------------|
| Starface Host/IP | `192.168.1.100` | IP-Adresse oder Hostname der Starface (nur für Zertifikat-Import) |
| Starface HTTPS-Port | `443` | Standard: 443 |
| Lokaler Port | `444` | Port für den lokalen Webserver (Standard: 444) |

> **Hinweis:** Login-Daten werden beim Setup nicht benötigt. Diese werden später im Add-in selbst in den Sync-Profilen konfiguriert.

### Was macht das Setup?

1. **Starface-Zertifikat importieren** - Verbindet sich zur Starface, extrahiert das SSL-Zertifikat und importiert es als vertrauenswürdig in den Windows-Zertifikatspeicher. Damit funktionieren die API-Aufrufe vom Add-in zur Starface.

2. **Lokale Zertifikate erstellen** - Erstellt eine lokale CA und ein davon signiertes localhost-Zertifikat. Die CA wird als vertrauenswürdig importiert. Damit läuft der lokale Webserver mit gültigem HTTPS.

3. **Lokalen Webserver einrichten** - Installiert einen minimalen Node.js HTTPS-Server als Windows Scheduled Task. Der Server startet automatisch beim Systemstart und liefert nur die statischen Add-in Dateien über `https://localhost:444` aus.

4. **Outlook Add-in registrieren** - Registriert das Add-in automatisch für Outlook Classic (per Registry). Für das neue Outlook wird eine Anleitung zur manuellen Einrichtung angezeigt.

### Nach der Installation

- **Outlook Classic**: Outlook neu starten. Im Ribbon erscheint der Button **"Kontakt-Sync"** in der Gruppe "Starface Sync".
- **Neues Outlook**: Manuell hinzufügen über Einstellungen → Add-Ins verwalten → Benutzerdefinierte Add-Ins → Aus Datei hinzufügen → `C:\Program Files\StarfaceOutlookSync\manifest-catalog\manifest.xml`

### Deinstallation

```powershell
# PowerShell als Administrator:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\uninstall.ps1
# oder direkt aus dem Installationsverzeichnis:
& "C:\Program Files\StarfaceOutlookSync\uninstall.ps1"
```

Die Deinstallation entfernt:
- Den lokalen Webserver (Scheduled Task)
- Die lokale CA und das localhost-Zertifikat
- Die Outlook-Registrierung
- Alle installierten Dateien

Das Starface-Zertifikat wird **nicht** entfernt, da es ggf. von anderen Anwendungen benötigt wird.

### Weitere Starface-Anlagen hinzufügen

Wenn im Add-in ein Sync-Profil zu einer weiteren Starface-Anlage eingerichtet wird, deren Zertifikat noch nicht importiert ist, schlägt der Verbindungstest fehl. Das Add-in zeigt dann einen entsprechenden Hinweis an.

Um das Zertifikat einer weiteren Anlage zu importieren:

```powershell
# PowerShell als Administrator:
cd "C:\Program Files\StarfaceOutlookSync"
.\import-cert.ps1 -StarfaceHost 192.168.2.200
# oder mit anderem Port:
.\import-cert.ps1 -StarfaceHost pbx2.firma.local -Port 8443
```

Danach funktioniert die Verbindung im Add-in sofort - kein Neustart nötig.

## Entwicklung

### Dependencies installieren

```bash
npm install
```

### Development Server starten

```bash
npm run dev
```

Startet einen lokalen HTTPS-Server auf `https://localhost:3000` mit einem Dev-Zertifikat (nur für Entwicklung).

### Production Build

```bash
npm run build
```

Die fertigen Dateien liegen anschließend im Ordner `dist/`.

### Manuelles Sideloading (zum Testen)

1. `npm run dev` starten
2. In Outlook: Datei → Add-Ins verwalten → Meine Add-Ins → "Benutzerdefiniertes Add-In hinzufügen" → `manifest.xml` auswählen

## Benutzung

1. In Outlook auf den Button **"Kontakt-Sync"** in der Ribbon-Leiste klicken
2. Ein neues Sync-Profil anlegen:
   - **Profilname** vergeben (z.B. "Firmenkontakte Hauptanlage")
   - **Starface-Verbindung** konfigurieren: Host/IP, Port, Login-ID und Kennwort eingeben
   - **Verbindung testen** um die Zugangsdaten zu prüfen
   - **Adressbücher laden** um die verfügbaren Starface-Adressbücher abzurufen
   - **Starface-Adressbuch** auswählen (Zentral, Persönlich oder Tag)
   - **Outlook-Kontaktordner** auswählen
   - **Synchronisationsrichtung** festlegen
3. Profil speichern
4. Über "Jetzt synchronisieren" die Kontakte abgleichen

Es können beliebig viele Profile angelegt werden, auch für unterschiedliche Starface-Anlagen.

## Projektstruktur

```
outlook-sync/
├── manifest.xml                  # Office Add-in Manifest
├── package.json                  # Dependencies & Scripts
├── webpack.config.js             # Build-Konfiguration
├── assets/                       # Add-in Icons
├── dist/                         # Build-Ausgabe
├── installer/
│   ├── setup.ps1                 # Installations-Script
│   ├── uninstall.ps1             # Deinstallations-Script
│   ├── import-cert.ps1           # Zertifikat-Import für weitere Anlagen
│   └── local-server.js           # Lokaler HTTPS-Webserver
└── src/
    ├── models/
    │   └── types.ts              # Datenmodelle
    ├── services/
    │   ├── starface-api.ts       # Starface REST API Client
    │   ├── outlook-contacts.ts   # Outlook REST API Client
    │   ├── sync-engine.ts        # Sync-Logik
    │   └── profile-manager.ts    # Profilverwaltung
    └── taskpane/
        ├── index.tsx             # Entry Point
        ├── taskpane.html         # HTML Template
        ├── styles/taskpane.css   # Styling
        └── components/
            ├── App.tsx           # Hauptkomponente
            ├── ProfileList.tsx   # Profilübersicht
            ├── ProfileEditor.tsx # Profil-Editor
            └── SyncView.tsx      # Sync-Ansicht
```

## Synchronisierte Kontaktfelder

| Feld | Outlook | Starface |
|------|---------|----------|
| Vorname | GivenName | NAME |
| Nachname | Surname | SURNAME |
| Firma | CompanyName | COMPANY |
| Position | JobTitle | JOB_TITLE |
| E-Mail | EmailAddresses | EMAIL |
| Telefon (Büro) | Business Phone | OFFICE_PHONE_NUMBER |
| Mobiltelefon | Mobile Phone | MOBILE_PHONE_NUMBER |
| Telefon (Privat) | Home Phone | PRIVATE_PHONE_NUMBER |
| Fax | Business Fax | FAX_NUMBER |
| Straße | Street | STREET |
| Stadt | City | CITY |
| PLZ | PostalCode | POSTAL_CODE |
| Bundesland | State | STATE |
| Land | CountryOrRegion | COUNTRY |
| Webseite | Websites | URL |
| Notizen | PersonalNotes | NOTE |
| Anrede | Title | SALUTATION |
| Titel | — | TITLE |
| Geburtstag | Birthday | BIRTHDAY |

## Technische Details

### Architektur

Das Add-in ist ein Office Web Add-in (funktioniert in Classic und New Outlook). Outlook lädt das Add-in als Webseite in einem eingebetteten Browser (WebView). Die Webseite kommuniziert dann direkt mit der Starface REST-API und der Outlook REST-API:

```
Outlook
  └── WebView (eingebetteter Browser)
        ├── Lädt UI von:         https://localhost:444  (lokaler Webserver)
        ├── Spricht direkt mit:  Starface REST-API
        └── Spricht direkt mit:  Outlook REST-API (Office.js)
```

### Zertifikate

Der lokale Webserver und die Starface verwenden HTTPS. Da die Starface typischerweise ein self-signed Zertifikat hat und der lokale Webserver ebenfalls ein lokales Zertifikat braucht, erstellt das Setup:

- Importiert das **Starface-Zertifikat** in den Windows Trusted Root Store → Outlook/WebView vertraut den API-Aufrufen zur Starface
- Erstellt eine **lokale CA** → wird in den Trusted Root Store importiert
- Erstellt ein **localhost-Zertifikat**, signiert von der lokalen CA → der lokale Webserver hat gültiges HTTPS

### Datenspeicherung

- **Sync-Profile**: `localStorage` im Outlook WebView
- **Sync-Mappings**: `localStorage` im Outlook WebView (Zuordnung Outlook-ID ↔ Starface-ID)
- **Server-Konfiguration**: `C:\Program Files\StarfaceOutlookSync\config.json`
- **Zugangsdaten**: Werden nur im Add-in (localStorage) gespeichert, nicht auf dem Dateisystem

## Lizenz

Proprietär - Alle Rechte vorbehalten.