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: Outlook -> Starface, Starface -> Outlook oder bidirektional
- **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/
├<EFBFBD><EFBFBD>─ 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

### SSL-Zertifikate

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

## Lizenz

Proprietaer - Alle Rechte vorbehalten.

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