[30e88f42] Einfügen

Einfügen

connector-superoffice/README.md

@@ -130,6 +130,22 @@ Die `config.py` wurde auf natives Python (`os.getenv`) umgestellt, um Konflikte
 Der Worker wurde erweitert, um auch `City` und `OrgNumber` (VAT) zurückzuschreiben.
 **Status (21.02.2026):** Implementiert, aber noch im Feinschliff. Logs zeigen teils Re-Queueing während das Enrichment läuft.
 
+### 8. Lessons Learned: Address & VAT Sync (Solved Feb 22, 2026)
+
+Die Synchronisation von Adressdaten stellte sich als unerwartet komplex heraus. Hier die wichtigsten Erkenntnisse für zukünftige Entwickler:
+
+1.  **Das "OrgNumber"-Phantom:**
+    *   **Problem:** In der API-Dokumentation oft als `OrgNumber` referenziert, akzeptiert die WebAPI (REST) strikt nur **`OrgNr`**.
+    *   **Lösung:** Mapping im `worker.py` hart auf `OrgNr` umgestellt.
+
+2.  **Verschachtelte Adress-Struktur:**
+    *   **Problem:** Ein flaches Update auf `PostalAddress` wird von der API stillschweigend ignoriert (HTTP 200, aber keine Änderung).
+    *   **Lösung:** Das Update muss die tiefe Struktur respektieren: `Address["Postal"]["City"]` UND `Address["Street"]["City"]`. Beide müssen explizit gesetzt werden, um in der UI sichtbar zu sein.
+
+3.  **Die "Race Condition" Falle (Atomic Updates):**
+    *   **Problem:** Wenn Adress-Daten (`PUT Contact`) und UDF-Daten (`PUT Contact/Udef`) in separaten API-Aufrufen kurz hintereinander gesendet werden, gewinnt der letzte Call. Da dieser oft auf einem *veralteten* `GET`-Stand basiert (bevor das erste Update durch war), wurde die Adresse wieder mit "Leer" überschrieben.
+    *   **Lösung:** **Atomic Update Strategy**. Der Worker sammelt *alle* Änderungen (Adresse, VAT, Vertical, Openers) in einem einzigen Dictionary und sendet genau **einen** `PUT`-Request an den Kontakt-Endpunkt. Dies garantiert Konsistenz.
+
 ## Appendix: The "First Sentence" Prompt
 
 This is the core logic used to generate the company-specific opener.