Nextcloud-App: Carddav to file sync 0.1.3

Die installierbare Nextcloud-App liegt in app/. Sie gleicht Tabellen in Nextcloud Files (xlsx, ods oder csv) mit einem CardDAV-Adressbuch ab. Benötigt werden Contacts und DAV. Einrichtung unter Persönliche Einstellungen → Carddav to file sync.

Der Abgleich kann Kontakte und Tabellenzeilen erstellen, ändern und löschen. Löschungen werden entsprechend der gewählten Richtung auf die andere Seite übertragen. Die Löschgrenze begrenzt die Anzahl pro Lauf; sie ersetzt keine Sicherung. „Jetzt synchronisieren“ verwendet die gespeicherten Einstellungen.

Bei der Deinstallation werden die Einstellungen aller Benutzer und die internen Sync-Stände entfernt. Die Tabellen, exportierten Bilder und Adressbücher sind Benutzerdokumente und bleiben erhalten. Nach erneuter Installation fehlt der bisherige Sync-Stand; die Daten werden erneut zusammengeführt.

Release bauen: make appstore. Die Version in app/appinfo/info.xml und app/CHANGELOG.md ist 0.1.3. Das erzeugte Archiv liegt unter build/telefonbuchsync.tar.gz. Für die Store-Einreichung müssen das Archiv und sein öffentlicher Quellcode aus demselben Commit stammen. Nach Änderungen das Archiv neu bauen und neu signieren; eine ältere Signatur ist dann ungültig.

PHP-Tests: vendor/bin/phpunit. Die zusätzlichen Deinstallationstests benötigen Nextclouds öffentliche PHP-Schnittstellen: NEXTCLOUD_ROOT=/pfad/zu/nextcloud vendor/bin/phpunit --no-configuration --bootstrap tests/nextcloud/bootstrap.php tests/nextcloud.

OpenCloud

Der eigenständige OpenCloud-Dienst hat eine eigene Version und Paketierung. Installation, Löschverhalten und Deinstallation: OpenCloud-Dokumentation.

Separater Python-Dienst

Die folgenden Abschnitte beschreiben den eigenständigen Python-Dienst.

Telefonbuch-Sync: Excel ⇄ Nextcloud-Kontakte

Gleicht eine Excel-Tabelle in Nextcloud Files täglich in beide Richtungen mit einem Nextcloud-Adressbuch ab. Kostenlos, selbst gehostet, nur Python und Nextcloud-Standardschnittstellen (WebDAV und CardDAV).

So funktioniert es

• Jede Zeile bekommt in der Spalte UID die Kennung ihres Kontakts.
• Nach jedem Lauf wird der gemeinsame Stand in state.json gespeichert. Beim nächsten Lauf erkennt das Skript pro Feld, welche Seite etwas geändert hat:

Situation	Ergebnis
nur in Excel geändert	wird in die Kontakte übernommen
nur in Kontakten geändert (Web, Handy, Outlook …)	wird in Excel übernommen
dasselbe Feld auf beiden Seiten geändert	conflict_winner gewinnt, wird im Log vermerkt
unterschiedliche Felder auf beiden Seiten geändert	beide Änderungen bleiben erhalten
neue Zeile in Excel	neuer Kontakt
neuer Kontakt	neue Zeile am Tabellenende
Zeile gelöscht	Kontakt wird gelöscht
Kontakt gelöscht	Zeile wird gelöscht
auf der einen Seite gelöscht, auf der anderen geändert	wird wiederhergestellt (nichts geht verloren)

Felder im Kontakt, die nicht gemappt sind (Foto, weitere Nummern …), bleiben unangetastet.

Sicherheitsnetz

• Vor jeder Änderung liegen Sicherungen in backups/: die Excel-Datei und alle Kontakte als .vcf.
• Mehr als max_deletions Löschungen in einem Lauf führen zum Abbruch.
• Ist Excel oder das Adressbuch plötzlich leer, bricht der Lauf ab (falsche Datei oder falsches Blatt?).
• Ist die Datei gerade in Nextcloud Office/OnlyOffice geöffnet (Dateisperre), wird der Lauf übersprungen. Das funktioniert nur, wenn die App Temporary files lock (files_lock) aktiv ist.
• Änderungen werden mit ETags geschrieben. Hat jemand parallel etwas geändert, wird nichts überschrieben; der nächste Lauf holt es nach.

Einrichtung

1. Benutzer und App-Passwort: Am besten einen eigenen Nextcloud-Benutzer wie telefonbuch anlegen, dem die Excel-Datei und das Adressbuch gehören (andere bekommen beides per Freigabe). Unter Einstellungen → Sicherheit ein App-Passwort erzeugen.
2. Adressbuch-Name: In Kontakte → Einstellungen beim Adressbuch den Link kopieren. Der letzte Teil der URL ist der Name, zum Beispiel …/addressbooks/users/telefonbuch/contacts/ → contacts.
3. Konfiguration:

   mkdir data && cp config.example.toml data/config.toml
   

   Dann URL, Benutzer, App-Passwort, Pfad und die Spaltenzuordnung [columns] anpassen.
4. Testlauf (ändert nichts):

   docker compose run --rm telefonbuch-sync --dry-run
   

5. Erster echter Lauf, danach als Dienst starten (täglich um run_at):

   docker compose run --rm telefonbuch-sync
   docker compose up -d
   

Ohne Docker geht es auch mit pip install -r requirements.txt und einem Cron-Eintrag: 0 3 * * * cd /opt/telefonbuch-sync && python3 sync.py -c config.toml >> sync.log 2>&1

Erster Lauf mit bestehenden Daten

Bestehende Excel-Zeilen und Kontakte werden über den Namen (Vor- und Nachname, sonst Firma oder E-Mail) einander zugeordnet und zusammengeführt. Es entstehen also keine Dubletten. Fehlt ein Wert auf einer Seite, wird er ergänzt. Nur wenn beide Seiten unterschiedliche Werte haben, gewinnt conflict_winner. Vorher unbedingt --dry-run ausführen und das Ergebnis prüfen.

Hinweise für die Excel-Pflege

• Spalte UID nicht bearbeiten. Wird eine Zeile samt UID kopiert, wird die Kopie als neuer Kontakt behandelt.
• Telefonnummern als Text formatieren, sonst entfernt Excel führende Nullen.
• Überschriften müssen den Namen in [columns] entsprechen (Groß-/Kleinschreibung egal).
• Formeln in den gemappten Spalten werden nicht unterstützt.
• Mit „Als Tabelle formatieren“ formatierte Bereiche wachsen bei neuen Zeilen automatisch mit.

Exit-Codes

0 ok · 1 Fehler · 2 Sicherheitsabbruch (Log prüfen, ggf. --force) · 3 Datei gesperrt oder Lauf aktiv

Tests

pip install -r requirements.txt pytest && pytest