starface-outlook-sync-addin/CHANGELOG.md

# Changelog

Alle nennenswerten Aenderungen an Starface Outlook Sync werden hier dokumentiert.

Format orientiert sich an [Keep a Changelog](https://keepachangelog.com/de/),
Versionsschema ist `x.x.x.x` (siehe `release.sh`).

## [Unreleased]

### Behoben

- **Dubletten auf beiden Seiten beim Synchronisieren.** Mehrere zusammenhaengende
  Ursachen wurden beseitigt:
  - Eine unvollstaendig geladene Starface-Kontaktliste (z.B. durch einen
    Lade-Fehler oder Timeout) liess die Engine Kontakte faelschlich als
    "geloescht" ansehen, ihr Mapping verwerfen und sie beim naechsten Lauf neu
    anlegen. Der Kontakt-Abruf bricht jetzt mit Fehlermeldung ab (inkl.
    Wiederholversuch), statt still mit einer Teil-Liste weiterzuarbeiten.
  - Ist ein Starface-Kontakt nicht in der geladenen Liste, wird er jetzt per
    ID direkt abgefragt: existiert er noch (liegt also in einem **anderen
    Adressbuch**), bleibt das Mapping erhalten und es wird nichts neu angelegt
    (keine Dublette). Ist er **wirklich geloescht** (404), wird er je nach
    Sync-Richtung in Starface neu angelegt bzw. die Loeschung nach Outlook
    gespiegelt. (Vorher wurde das Mapping faelschlich behalten und der Kontakt
    in Outlook->Starface gar nicht neu angelegt.)
  - Das Wiederzuordnen bestehender Kontakte war zu streng: eine von Starface
    umformatierte Telefonnummer konnte einen eindeutigen E-Mail- oder
    Namens-Treffer ueberstimmen und so eine Neuanlage statt Verknuepfung
    ausloesen. Ein gleicher E-Mail- oder voller Namens-Treffer reicht jetzt.

- **Synchronisation extrem langsam / schrieb bei jedem Lauf alle Kontakte neu.**
  Die Aenderungserkennung verglich einen einzigen Hash gegen beide Seiten.
  Outlook und Starface stellen denselben Kontakt aber unterschiedlich dar
  (nicht uebertragene Felder, abweichendes Telefonformat), wodurch der Hash nie
  uebereinstimmte und praktisch jeder Kontakt bei jedem Sync neu geschrieben
  wurde. Jede Seite hat jetzt eine eigene Baseline (`LastOutlookHash` /
  `LastStarfaceHash`); nur tatsaechlich geaenderte Kontakte werden geschrieben.

### Hinzugefuegt

- **Protokoll zeigt jetzt, WAS geaendert wurde.** Pro Sync werden die einzelnen
  Aktionen (erstellt / aktualisiert / geloescht / verknuepft / zusammengefuehrt je
  Kontakt) ins Protokoll geschrieben - sowohl beim manuellen Sync (Fenster) als
  auch bei Auto-/Tray-Sync.
- **Benachrichtigungen schaltbar (Einstellungen).** Zwei unabhaengige Haken:
  "Tray-Benachrichtigungen (allgemein)" fuer Info-Meldungen (Sync laeuft/fertig)
  und "Benachrichtigungen bei Warnungen/Fehlern" fuer Konflikte und Fehler. So
  kann man z.B. nur noch bei Konflikten/Fehlern benachrichtigt werden - oder gar
  nicht. Das Protokoll wird unabhaengig davon immer geschrieben.
- **Protokoll (Logdatei) + "Protokoll"-Button.** Syncs, Ergebnisse, Konflikte
  (lokal und von anderen Arbeitsplaetzen) und Fehler werden dauerhaft in
  `%AppData%\StarfaceOutlookSync\sync.log` festgehalten - so ist auch nach dem
  Verschwinden einer Tray-Meldung nachvollziehbar, wer/was/wann. Im Hauptfenster
  oeffnet der Button "Protokoll" einen Betrachter (Aktualisieren/Leeren/Ordner
  oeffnen). Die Datei rotiert bei 2 MB.
- **Clientuebergreifende Konflikt-Hinweise (Mehrplatz).** Wird ein echter
  Feld-Konflikt aufgeloest, legt der Client eine Notiz im gemeinsamen Verzeichnis
  (`conflicts/`) ab - zugeordnet nach Kontakt (StarfaceId). Ein anderer
  Arbeitsplatz zeigt die Meldung beim naechsten Sync nur an, wenn er den Kontakt
  selbst hat UND sein eigener Feldwert vom uebernommenen Wert abweicht - so wird
  der ueberschriebene Arbeitsplatz gewarnt, waehrend bereits aktuelle Clients
  nicht benachrichtigt werden. Bereits gezeigte Notizen merkt sich jeder Client
  lokal; alte Notizen werden nach 7 Tagen aufgeraeumt.
- **Clientuebergreifende Sync-Sperre (Mehrplatz).** In den Einstellungen laesst
  sich ein gemeinsames Verzeichnis (Netzlaufwerk/UNC) hinterlegen. Synct ein
  Arbeitsplatz, legt er dort eine Lock-Datei an (atomar via `CreateNew`); andere
  Clients warten, bis sie frei ist (bis 2 Min, sonst wird der Lauf uebersprungen).
  Stuerzt ein Client ab, uebernimmt ein anderer die verwaiste Sperre. Ist kein
  Verzeichnis konfiguriert oder nicht erreichbar, wird ohne diese Sperre
  weitergearbeitet (der lokale Schutz auf dem PC bleibt).
- **Feldweises 3-Wege-Merge bei Konflikten (bidirektional).** Wenn derselbe
  Kontakt zwischen zwei Syncs auf beiden Seiten geaendert wurde, bleiben jetzt
  Aenderungen an *unterschiedlichen* Feldern beide erhalten (z.B. einer aendert
  die Telefonnummer in Outlook, ein anderer die E-Mail in Starface). Nur wenn
  DASSELBE Feld auf beiden Seiten unterschiedlich geaendert wurde, greift die
  Vorrang-Regel (Outlook gewinnt). Dafuer wird im Mapping zusaetzlich ein
  Snapshot des letzten Sync-Stands je Seite gespeichert. Solche echten
  Feld-Konflikte werden dem Benutzer per Tray-Meldung angezeigt.

### Geaendert

- **Manueller und automatischer Sync vereinheitlicht.** Beide Pfade laufen jetzt
  ueber einen gemeinsamen `SyncCoordinator` und nutzen damit dieselben Schutz-
  und Komfortfunktionen: lokaler Re-Entrancy-Schutz (prozessweit - auch manuell
  vs. automatisch koennen nicht mehr gleichzeitig laufen), clientuebergreifende
  Lock-Datei, Konflikt-Notizen anderer Arbeitsplaetze und vollstaendiges
  Protokoll. Vorher umging der manuelle "Synchronisieren"-Button (Fenster) die
  Lock-Datei und einen Teil des Protokolls.
- **Doppelte Syncs verhindert (lokal).** Der Schutz gegen gleichzeitig laufende
  Syncs (manuell + Auto-Sync-Timer) ist jetzt atomar (`Interlocked`) statt eines
  nicht-atomaren `volatile bool`, bei dem beide in einem Zeitfenster
  durchrutschen konnten.
- **Ein-Richtungs-Modi sind jetzt echtes "Ersetzen".** Outlook->Starface macht
  das Starface-Adressbuch zu einer exakten Kopie von Outlook: Kontakte, die nur
  in Starface existieren (kein Pendant in Outlook), werden geloescht.
  Starface->Outlook entsprechend umgekehrt. Schutz: Ist die Quelle komplett
  leer (z.B. falscher Ordner gewaehlt), wird die Loeschphase uebersprungen
  statt die Zielseite zu leeren. Mass-Loeschungen finden nur bei vollstaendig
  geladener Liste statt (unvollstaendige Ladevorgaenge brechen vorher ab).
- **Bidirektionale Loeschungen** werden jetzt erkannt. Wird ein Kontakt auf
  einer Seite geloescht und ist die andere Seite seit dem letzten Sync
  unveraendert (Abgleich ueber die gespeicherte Baseline), wird die Loeschung
  auf die andere Seite gespiegelt – statt den Kontakt wieder anzulegen. Wurde
  die andere Seite zwischenzeitlich bearbeitet, gewinnt die Bearbeitung und der
  Kontakt wird neu angelegt (kein Datenverlust). In den Ein-Richtungs-Modi
  bleibt die jeweilige Quelle fuehrend (Loeschung im Ziel wird wiederhergestellt).
- Starface-Kontaktdetails werden beim Laden parallel abgerufen (8 gleichzeitig)
  statt einzeln nacheinander – deutlich schneller bei grossen Adressbuechern.
- `UpdateContact` (Outlook) und `UpdateContactAsync` (Starface) geben jetzt den
  frisch eingelesenen Stand zurueck, damit die Baseline nach dem Schreiben
  korrekt gesetzt wird und der Sync sauber konvergiert.

### Migration

- Bestehende Mapping-Dateien werden beim ersten Sync automatisch uebernommen
  (ein ruhiger Durchlauf ohne Massen-Update).
- **Bereits vorhandene Dubletten werden nicht automatisch entfernt** – die Fixes
  verhindern nur neue. Vorhandene Doppel-Kontakte einmalig manuell bereinigen.

## [0.0.0.23]

### Behoben

- Kritischer Loesch-Fehler: Kontakte wurden bei einer geaenderten Outlook-EntryID
  nicht mehr massenhaft geloescht.

### Geaendert

- Outlook-Sicherheitsschluessel werden fuer Domaenenumgebungen zusaetzlich nach
  HKLM geschrieben (unterdrueckt die Outlook-Sicherheitsabfrage).

## Aeltere Versionen

Aeltere Releases (v0.0.0.1 – v0.0.0.22) sind ueber die Git-Historie und die
Git-Tags nachvollziehbar.