starface-outlook-sync-addin/README.md

# Starface Kontakt-Sync

Windows-Anwendung 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 (verschiedene Adressbuecher oder Anlagen)
- **Starface-Adressbuecher**: Zentrales Adressbuch, persoenliches Adressbuch und Tag-basierte Adressbuecher
- **Outlook-Kontaktordner**: Frei waehlbarer Kontaktordner als Sync-Ziel
- **Sync-Richtung** konfigurierbar:
  - *Bidirektional*: Aenderungen werden in beide Richtungen abgeglichen (inkl. Loeschungen)
  - *Outlook -> Starface*: Das Starface-Adressbuch wird zur exakten Kopie von Outlook (nur in Starface vorhandene Kontakte werden geloescht)
  - *Starface -> Outlook*: Der Outlook-Ordner wird zur exakten Kopie von Starface (nur in Outlook vorhandene Kontakte werden geloescht)
- **Intelligentes Matching**: Kontakte werden anhand von E-Mail-Adresse oder Name abgeglichen
- **Aenderungserkennung**: Nur geaenderte Kontakte werden uebertragen (Hash-basiert)
- **Auto-Sync**: Optionaler automatischer Sync in konfigurierbarem Intervall
- **System Tray**: Laeuft im Hintergrund, Schnell-Sync per Rechtsklick
- **Kompatibel** mit Outlook Classic und dem neuen Outlook
- **Komplett lokal**: Kein Exchange, kein Microsoft 365, kein Cloud-Konto erforderlich

## Voraussetzungen

- Windows 10/11
- .NET 8 Desktop Runtime (Setup prueft und verlinkt die Download-Seite falls noetig)
- Microsoft Outlook (Classic oder Neu, beliebige Version)
- Starface Telefonanlage ab Version 6.7 (REST-API)

## Installation beim Kunden

### Setup ausfuehren

1. `StarfaceOutlookSync_Setup_0.0.0.1.exe` ausfuehren
2. Installationsoptionen waehlen:
   - Desktop-Verknuepfung erstellen (optional)
   - Bei Windows-Anmeldung automatisch starten (empfohlen)
3. Fertig - die App startet automatisch

### Nach der Installation

1. App starten (Tray-Icon oder Desktop-Verknuepfung)
2. "Neues Profil" klicken
3. Starface-Verbindungsdaten eingeben (Host, Login-ID, Kennwort)
4. "Verbindung testen" und "Adressbuecher laden"
5. Starface-Adressbuch und Outlook-Kontaktordner waehlen
6. Speichern und "Jetzt synchronisieren"

### Outlook-Sicherheitsabfrage unterdruecken

Beim Zugriff auf Outlook-Kontakte zeigt Outlook standardmaessig einen
Sicherheitsdialog ("Ein Programm versucht auf Ihre E-Mail-Adressinformationen
zuzugreifen"). Dieser kann in den Einstellungen der App deaktiviert werden:

1. In der App auf "Einstellungen" klicken
2. "Outlook-Sicherheitsabfrage automatisch erlauben" aktivieren
3. Speichern

**Auf Domaenen-PCs / Terminal Servern:**

Die Outlook-Sicherheitseinstellungen werden dort per Gruppenrichtlinie (GPO)
gesteuert und sind im Trust Center ausgegraut. In diesem Fall muss die App
**einmalig als Administrator** gestartet werden, damit die Registry-Keys
unter HKLM geschrieben werden koennen:

1. Rechtsklick auf die App -> "Als Administrator ausfuehren"
2. Einstellungen -> "Outlook-Sicherheitsabfrage automatisch erlauben" aktivieren
3. Speichern und App schliessen
4. Outlook neu starten
5. App kann danach wieder normal (ohne Admin) gestartet werden

Die Einstellung bleibt dauerhaft bestehen und gilt fuer alle Benutzer
auf dem Rechner.

### Deinstallation

Ueber Windows Einstellungen -> Apps oder die Systemsteuerung.
Benutzerdaten (Profile, Mappings) werden mit entfernt.

## Entwicklung

### Voraussetzungen (Build)

- .NET 8 SDK (laeuft auf Windows, Linux und macOS)
- Fuer den Installer: Inno Setup 6 (Windows) oder Docker (Linux)

### .NET SDK installieren

**Windows:**
```
winget install Microsoft.DotNet.SDK.8
```

**Debian/Ubuntu:**
```bash
# Ueber das offizielle Install-Script:
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 8.0
export PATH="$HOME/.dotnet:$PATH"
```

### Bauen

Das Projekt kann sowohl unter Windows als auch unter Linux gebaut werden.
Die fertige EXE laeuft nur auf Windows (WinForms + COM Interop).

```bash
# Release-Build
dotnet build src/StarfaceOutlookSync/StarfaceOutlookSync.csproj -c Release

# Oder publish (mit allen Abhaengigkeiten):
dotnet publish src/StarfaceOutlookSync/StarfaceOutlookSync.csproj -c Release
```

Build-Ausgabe: `src/StarfaceOutlookSync/bin/Release/net8.0-windows/win-x64/`

### Installer erstellen

Die Setup-EXE wird mit Inno Setup 6 erstellt.

**Linux (Docker - empfohlen):**

Einfachster Weg unter Linux. Baut und packt alles in einem Schritt:

```bash
# 1. Release bauen
dotnet build src/StarfaceOutlookSync/StarfaceOutlookSync.csproj -c Release

# 2. Installer erstellen
docker run --rm -v "$PWD:/work" amake/innosetup installer/setup.iss
```

Die fertige Setup-EXE liegt danach in `dist/`.

Komplett als Einzeiler (Build + Installer):
```bash
dotnet build src/StarfaceOutlookSync/StarfaceOutlookSync.csproj -c Release && docker run --rm -v "$PWD:/work" amake/innosetup installer/setup.iss
```

**Windows:**

1. [Inno Setup 6](https://jrsoftware.org/isinfo.php) installieren
2. `installer/setup.iss` oeffnen und kompilieren
3. Setup-EXE wird in `dist/` erstellt

Oder per Kommandozeile:
```cmd
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\setup.iss
```

**Linux (Wine - Alternative falls kein Docker vorhanden):**
```bash
# Einmalig: Inno Setup in Wine installieren
sudo apt install wine
wine ~/Downloads/innosetup-6.x.exe

# Kompilieren
wine "$HOME/.wine/drive_c/Program Files (x86)/Inno Setup 6/ISCC.exe" installer/setup.iss
```

### Release erstellen

Das Release-Script automatisiert den kompletten Release-Prozess:
Versionsnummer aktualisieren, bauen, Installer erstellen, Git Tag + Push
und Gitea Release mit Setup-EXE als Download hochladen.

```bash
./release.sh <version> ["beschreibung"]
```

Beispiele:
```bash
# Release mit Standard-Beschreibung
./release.sh 0.1.0.0

# Release mit eigener Beschreibung
./release.sh 0.2.0.0 "Neues Feature: Auto-Sync"
```

Das Script fragt beim Start nach Gitea-Benutzername und Kennwort
und fuehrt dann folgende Schritte automatisch aus:

1. Prueft Voraussetzungen (dotnet, docker, curl, sauberes git)
2. Aktualisiert Versionsnummer in `.csproj`, `AboutForm.cs` und `setup.iss`
3. Baut das Projekt (`dotnet build -c Release`)
4. Erstellt den Installer via Docker (`amake/innosetup`)
5. Git Commit + Tag (`vX.X.X.X`)
6. Push zu Gitea (main + tag)
7. Erstellt Gitea Release mit Setup-EXE als Download-Anhang

Voraussetzungen:
- .NET 8 SDK
- Docker
- curl
- Gitea-Account mit Push-Rechten auf das Repository

## Projektstruktur

```
outlook-sync/
├��─ StarfaceOutlookSync.sln          # Visual Studio Solution
├── installer/
│   └── setup.iss                     # Inno Setup Script
└── src/StarfaceOutlookSync/
    ├── StarfaceOutlookSync.csproj    # Projektdatei
    ├── Program.cs                    # Entry Point (Single Instance)
    ├── Models/
    │   ├── UnifiedContact.cs         # Kontakt-Datenmodell
    │   └── SyncProfile.cs           # Profile, Mappings, Ergebnisse
    ├── Services/
    │   ├── StarfaceApiClient.cs      # Starface REST-API Client
    │   ├── OutlookContactsService.cs # Outlook COM Interop
    │   ├── ProfileManager.cs         # Profilverwaltung (AppData)
    │   └── SyncEngine.cs            # Bidirektionale Sync-Logik
    └── UI/
        ├── MainForm.cs              # Hauptfenster + System Tray
        ├── ProfileEditorForm.cs     # Profil anlegen/bearbeiten
        ├── SyncProgressForm.cs      # Sync-Fortschritt mit Log
        └── AboutForm.cs             # Info-Dialog
```

## Synchronisierte Kontaktfelder

| Feld | Outlook (COM) | Starface (REST) |
|------|---------------|-----------------|
| Vorname | FirstName | NAME |
| Nachname | LastName | SURNAME |
| Firma | CompanyName | COMPANY |
| Position | JobTitle | JOB_TITLE |
| E-Mail | Email1Address | EMAIL |
| Telefon (Buero) | BusinessTelephoneNumber | OFFICE_PHONE_NUMBER |
| Mobiltelefon | MobileTelephoneNumber | MOBILE_PHONE_NUMBER |
| Telefon (Privat) | HomeTelephoneNumber | PRIVATE_PHONE_NUMBER |
| Fax | BusinessFaxNumber | FAX_NUMBER |
| Strasse | BusinessAddressStreet | STREET |
| Stadt | BusinessAddressCity | CITY |
| PLZ | BusinessAddressPostalCode | POSTAL_CODE |
| Bundesland | BusinessAddressState | STATE |
| Land | BusinessAddressCountry | COUNTRY |
| Webseite | WebPage | URL |
| Notizen | Body | NOTE |
| Anrede | Title | SALUTATION |
| Geburtstag | Birthday | BIRTHDAY |

## Technische Details

### Architektur

Die Anwendung ist eine native Windows-App (WinForms, .NET Framework 4.8). Sie greift direkt per COM Interop auf Outlook-Kontakte zu und kommuniziert per REST-API mit der Starface. Kein Webserver, kein Browser, kein Exchange erforderlich.

```
StarfaceOutlookSync.exe
  ├── COM Interop -> Outlook Kontakte (lokal)
  ├── REST-API    -> Starface Telefonanlage (HTTPS)
  └── Dateisystem -> Profile & Mappings (%AppData%)
```

### Datenspeicherung

Alle Daten werden lokal pro Benutzer gespeichert:
- `%AppData%\StarfaceOutlookSync\profiles.json` - Sync-Profile mit Zugangsdaten
- `%AppData%\StarfaceOutlookSync\mappings\` - Kontakt-Zuordnungen pro Profil
- `%AppData%\StarfaceOutlookSync\sync.log` - Protokoll (Syncs, Konflikte, Fehler);
  im Hauptfenster ueber den Button **Protokoll** einsehbar

### SSL-Zertifikate

Self-signed Zertifikate der Starface werden automatisch akzeptiert. Es ist kein manueller Zertifikat-Import erforderlich.

### Mehrplatz-Betrieb / Sync-Sperre

Mehrere Arbeitsplaetze koennen dasselbe Starface-Adressbuch pflegen. Damit sich
gleichzeitig laufende Syncs nicht ins Gehege kommen (Dubletten, ueberschriebene
Aenderungen), gibt es zwei Schutzebenen:

**1. Lokal (immer aktiv):** Auf einem PC kann nie mehr als ein Sync gleichzeitig
laufen. Startet der Auto-Sync-Timer, waehrend ein manueller Sync laeuft (oder
umgekehrt), wird der zweite Lauf uebersprungen. Atomar per `Interlocked`.

**2. Clientuebergreifend (optional):** In den Einstellungen kann ein
**gemeinsames Verzeichnis** (Netzlaufwerk oder UNC-Pfad wie
`\\server\freigabe\sync`) hinterlegt werden. Funktionsweise:

- Beim Start eines Syncs legt der Client dort die Datei **`starface-sync.lock`**
  an - **atomar** ueber `FileMode.CreateNew`: das Anlegen schlaegt fehl, wenn
  die Datei bereits existiert. Damit kann immer nur ein Client gleichzeitig die
  Sperre halten.
- Die Datei wird waehrend des gesamten Syncs **offen gehalten** und am Ende
  wieder **geloescht**. Sie existiert also nur, solange tatsaechlich gerade
  synchronisiert wird (bei kleinen Adressbuechern nur sehr kurz).
- Inhalt der Datei: `Rechnername | Benutzer | UTC-Zeitstempel | Prozess-ID` -
  damit man sieht, wer gerade synct.
- Findet ein anderer Client die Sperre vor, **wartet** er (Abfrage alle 3
  Sekunden, bis zu 2 Minuten) und synct erst danach. Wird die Sperre nicht frei,
  wird der Lauf uebersprungen und beim naechsten Intervall erneut versucht.
- **Absturzsicher:** Stuerzt ein Client mitten im Sync ab, gibt Windows das
  Datei-Handle frei. Die verwaiste Lock-Datei gilt nach 15 Minuten als veraltet
  und wird vom naechsten Client uebernommen. Lebt der Halter noch, scheitert das
  Loeschen am offenen Handle - die Sperre bleibt also korrekt bestehen.
- Ist **kein** Verzeichnis konfiguriert oder es ist nicht erreichbar, laeuft der
  Sync ohne diese Sperre weiter (die lokale Sperre bleibt aktiv).

**Konflikt-Hinweise:** Wird im bidirektionalen Modus ein echter Feld-Konflikt
aufgeloest (dasselbe Feld auf beiden Seiten unterschiedlich geaendert, Outlook
gewinnt), legt der Client eine Notiz im Unterordner `conflicts/` des gemeinsamen
Verzeichnisses ab - zugeordnet ueber die StarfaceId des Kontakts. Beim naechsten
Sync zeigt ein anderer Arbeitsplatz die Meldung als Tray-Hinweis - aber **nur,
wenn er den Kontakt selbst hat UND sein eigener Feldwert vom uebernommenen Wert
abweicht** (so erfaehrt der ueberschriebene Arbeitsplatz davon, waehrend Clients,
die den Wert ohnehin schon haben, nicht benachrichtigt werden). Gezeigte Notizen
merkt sich jeder Client lokal, veraltete Notizen werden nach 7 Tagen entfernt.

> Hinweis: Im Mehrplatz-Betrieb sollte die **bidirektionale** Sync-Richtung
> verwendet werden. Die Ein-Richtungs-Modi ("Ersetzen") wuerden die von anderen
> Arbeitsplaetzen gepflegten Kontakte loeschen.

## Lizenz

Proprietaer - Alle Rechte vorbehalten.

HackerSoft - Hacker-Net Telekommunikation
Stefan Hacker
Am Wunderburgpark 5b
26135 Oldenburg