rinkplanner/docs/sync.md
torsten ab88a84d5d feat: Kür-Hub in der App anbinden
- Hub-Adresse und API-Token in den Sync-Einstellungen verbinden
- Verbindungstest über /api/v1/me, Token getrennt unter user://hub.cfg
- Datei → Kür-Hub… nur bei geprüfter Verbindung
- Alle veröffentlichten Küren durchsuchen, laden, veröffentlichen, verstecken
- Kollisionen: nummerierte Kopie mit Musik-Umbenennung oder Überschreiben
- HubSettings/HubClient/HubJob mit Worker-Thread und SHA-256-Prüfung
- Tests für Einstellungen, Fehler, Menü, Download und Kollisionen
2026-11-11 13:45:25 +01:00

11 KiB
Raw Blame History

Kür-Sync über Cloud-Speicher

Der Abgleich zwischen Desktop und Tablet läuft manuell über den eigenen Cloud-Speicher des Nutzers: Dropbox. Google Drive ist im Code vorbereitet, aber derzeit nicht freigeschaltet. Jeder Nutzer verbindet sein eigenes Konto; die App speichert nur den Refresh-Token lokal auf dem Gerät.

Der Kür-Hub ist etwas anderes: eine gemeinsame Beta-Ablage, in der ausgewählte Küren mit anderen Konten getauscht werden. Er ersetzt den Cloud-Sync nicht und wird in den Sync-Einstellungen separat verbunden (siehe docs/hub.md).

Einrichten

  1. Auf beiden Geräten: Datei → Sync-Einstellungen…
  2. Anbieter wählen: Dropbox.
  3. Verbinden… drücken und im Browser mit dem eigenen Dropbox-Konto anmelden. Die App öffnet die Dropbox-Seite; den dort angezeigten Code in das Feld einfügen und Verbinden drücken.
  4. Speichern.

Der Sync nutzt direkt den Dropbox-App-Ordner Apps/<App-Name>. Ein eigener Cloud-Unterordner wird nicht mehr abgefragt.

Danach Datei → Jetzt synchronisieren.

Auf dem Tablet muss das Konto ebenfalls einmal verbunden werden. Beide Geräte können dasselbe Dropbox-Konto verwenden; der Abgleich läuft über den gemeinsamen App-Ordner.

Was passiert

  • Jede Kür liegt als .json unter user://routines/ und wird 1:1 in den App-Ordner gespiegelt (flach, keine Unterordner). Gehört eine Musikdatei zur Kür (.mp3, .ogg, .wav), liegt sie im selben Ordner und wird mit denselben Regeln hoch- und heruntergeladen. Legacy-.tres-Dateien werden weiterhin mit synchronisiert, damit bestehende Installationen ihre Cloud-Kopien nicht verlieren; neue Speicherungen schreiben .json. Beim Laden wird eine .tres vor dem ResourceLoader gegen eine Whitelist geprüft (nur Modellskripte, kein eingebettetes GDScript).
  • Der Sync vergleicht pro Datei den letzten gemeinsamen Stand (user://sync_state.cfg) mit den aktuellen Zeitstempeln:
Lage Aktion
nur lokal, noch nie synchronisiert hochladen
nur in der Cloud herunterladen
seit dem letzten Sync nur lokal geändert hochladen
seit dem letzten Sync nur in der Cloud geändert herunterladen
beidseitig geändert (seit dem letzten Sync) neueste Fassung gewinnt: ältere Fassung wandert ins Konfliktarchiv
Datei auf einer Seite gelöscht nichts tun (keine Löschweitergabe)
erster Sync, Datei auf beiden Seiten neueste Fassung gewinnt: ältere Fassung wandert ins Konfliktarchiv

Wie entscheidet der Sync, welche Fassung neuer ist?

  • Bei .json-Küren zählt der Inhalt: Jede Speicherung schreibt saved_at (Unix-Zeit) in die Datei. Der Sync lädt die Cloud-Fassung in eine temporäre Datei und vergleicht beide Zeitstempel. Damit sind Geräte-Dateizeiten und Upload-Zeitpunkte unerheblich.
  • Bei Legacy-.tres- und Musikdateien gibt es keinen Inhalt-Zeitstempel. Dort vergleicht der Sync die lokale Dateizeit mit der Cloud-Änderungszeit.
  • Bei Gleichstand oder unbekannten Zeiten gilt: Beim ersten Abgleich ohne gemeinsamen Stand übernimmt die Cloud-Fassung, bei einem echten Konflikt bleibt die lokale Fassung.

Kürdateien aus älteren Versionen haben noch kein saved_at. Dort greift beim ersten Abgleich die Dateizeit als Ersatz; ab der nächsten Speicherung trägt die JSON den Inhalt-Zeitstempel.

Die unterlegene Fassung wird nicht mehr sichtbar neben die Kür gelegt. Sie landet unter user://conflicts/<dateiname> – ein Archivplatz pro Datei, der bei der nächsten Auflösung überschrieben wird. Erreichbar über Datei → Küren verwalten… → Konfliktkopien → Konfliktarchiv öffnen. So entstehen keine (Server …)-/(Lokal …)-Kopien mehr in der Kürliste.

Alte Kopien aus früheren Versionen bleiben zunächst liegen. Über Datei → Küren verwalten… → Konfliktkopien → Konfliktkopien suchen… sucht der Sync nach solchen Kopien, deren Hauptdatei noch existiert, zeigt sie in einem Dialog und verschiebt sie nach Bestätigung ins Konfliktarchiv. Cloud-Kopien werden dabei aus dem Cloud-Ordner gelöscht, damit sie nicht beim nächsten Sync zurückkommen. Kopien ohne Hauptdatei werden nicht angefasst – sie könnten die einzige erhaltene Fassung sein.

Normale, nicht mehr benötigte Küren lassen sich ebenfalls über Datei → Küren verwalten… löschen. Die Cloud-Kopie wird auf Wunsch mitgelöscht; die Musikdatei nur, wenn keine andere Kür sie verwendet.

Umbenennen ändert Dateinamen und Titel der Kür. Mit verbundenem Cloud-Konto wird auch die Cloud-Kopie umbenannt und der alte Sync-Stand entfernt. Ohne Cloud-Verbindung bleibt die alte Cloud-Kopie bestehen; der Sync holt sie dank des bisherigen Sync-Stands nicht als zweite Kür zurück, lädt aber die neue lokale Fassung hoch.

Wie kommt eine Kür vom Desktop aufs Tablet?

  1. Auf dem Desktop die Kür speichern (Datei → Speichern) und synchronisieren.
  2. Auf dem Tablet zuerst synchronisieren, dann Datei → Öffnen. Die Kür wird heruntergeladen und erscheint in der Liste.

Wichtig: Der Abgleich ordnet Dateien über den Dateinamen zu (der aus dem Kür-Titel entsteht). Eine Kür mit demselben Namen auf beiden Geräten ist kein „Update“, sondern eine Kollision. Der Sync löst sie anhand des Inhalt-Zeitstempels auf; die ältere Fassung bleibt im Konfliktarchiv, statt die Kürliste zu füllen. Bereits vorhandene alte (Server …)-/(Lokal …)- Kopien werden nicht automatisch gelöscht.

Wenn du auf dem Tablet also eine leere „Testkür1“ anlegst, obwohl es die Desktop-Version schon gibt, gewinnt nach dem Sync die Fassung mit dem neueren saved_at. Besser: erst synchronisieren, dann die vorhandene Kür öffnen und bearbeiten.

  • Vor dem Sync wird eine geänderte, bereits gespeicherte Kür automatisch gespeichert. Eine noch nie gespeicherte Kür öffnet zuerst „Speichern unter“.
  • Läuft der Sync, zeigt die Statusleiste den Fortschritt; danach erscheint eine Zusammenfassung (hochgeladen / heruntergeladen / aufgelöste Konflikte / Fehler).
  • Ist die geöffnete Kür vom Download betroffen und ungespeichert, wird sie nicht überschrieben – es erscheint ein Hinweis.

Technik

Datei Aufgabe
src/core/sync/remote_store.gd gemeinsame Schnittstelle der Cloud-Anbieter
src/core/sync/dropbox_store.gd Dropbox-API (App-Ordner, files/list_folder, files/upload, files/download, files/move_v2)
src/core/sync/google_drive_store.gd Google-Drive-API v3 (drive.file-Scope, Ordner Rinkplanner, Multipart-Upload, alt=media-Download)
src/core/sync/cloud_http.gd blockierender HTTPS-Client für den Worker-Thread
src/core/sync/cloud_auth.gd Refresh-Token, Access-Token-Erneuerung
src/core/sync/cloud_oauth_job.gd Google-Device-Flow und Dropbox-PKCE-Flow
src/core/sync/sync_app_config.gd App-Client-ID/App-Key laden
src/core/sync/sync_plan.gd reine Vergleichslogik, Zeitstempel, Gleichstandsregel
src/core/sync/routine_sync.gd Ablauf, Datei-Ersetzung, Sync-Stand
  • Der Sync läuft in einem Thread; die Oberfläche bleibt bedienbar und pollt den Fortschritt in _process.
  • Cloud-Uploads sind einzelne, atomare HTTP-Anfragen (Dropbox files/upload mit mode: overwrite, Google Drive Multipart-Upload). Ein zusätzliches .uploading-Umbenennen wie beim alten FTP-Sync entfällt.
  • Downloads landen in name.part und ersetzen die Zieldatei erst danach.
  • Heruntergeladene .json-Dateien werden als JSON validiert; Legacy-.tres laufen vor dem Laden durch die Whitelist in RoutineFile. Ein manipuliertes Cloud-Konto kann damit keine eingebetteten GDScripts ausführen.
  • Neue Speicherungen sind JSON; der Sync akzeptiert weiterhin .tres, damit bestehende Dateien in der Cloud und auf dem Tablet nicht verschwinden.
  • Musikdateien werden als normale Anhänge der Kür behandelt: Die JSON nennt nur den Dateinamen (music_file), die Datei liegt daneben. Ändert sich die Musik auf einem Gerät, lädt der nächste Sync sie hoch; auf dem anderen Gerät wird sie heruntergeladen und beim Öffnen der Kür verwendet. Bei einer Kollision gewinnt die neuere Dateizeit; die ältere landet unter user://conflicts/.
  • Eigene Timeline-Labels stehen in der Kür-JSON (timeline_labels) und werden ohne Zusatzdateien mit der Kür übertragen.
  • Refresh-Tokens liegen in user://sync.cfg (Klartext, app-privat). Auf Android ist das der interne App-Speicher, auf dem Desktop ~/.local/share/godot/app_userdata/Rinkplanner/. Nutzerpasswörter werden nicht gespeichert. Nach einem Kontowechsel oder Anbieterwechsel wird user://sync_state.cfg zurückgesetzt, damit alte Zeitstempel keinen falschen Konflikt auslösen.
  • Android braucht die INTERNET-Berechtigung – ist im APK gesetzt.

Datenschutz und Musiklizenzen

  • Bei Google Drive nutzt die App den Scope drive.file: Sie sieht nur Dateien, die Rinkplanner selbst angelegt hat, nicht das übrige Drive.
  • Bei Dropbox ist die App auf einen App-Ordner beschränkt.
  • Musikdateien werden im Konto des Nutzers gespeichert. Es gibt keinen zentralen Rinkplanner-Speicher und keine Weitergabe zwischen Konten. Die Verantwortung für die Nutzungsrechte liegt beim Nutzer.
  • Die App zeigt diesen Hinweis in den Sync-Einstellungen und sollte ihn auch in der Datenschutzerklärung für Stores führen.

Einrichtung der OAuth-Apps

Die App-Registrierung bei Google und Dropbox, die nötigen Scopes und die Werte in docs/credentials.txt stehen in docs/cloud-setup.md.

Grenzen

  • Kein automatischer Sync, kein Push, kein Locking. Zwei Geräte, die gleichzeitig synchronisieren, können sich überholen; der Sync behält dann die neuere Fassung und legt die ältere ins Konfliktarchiv.
  • Löschungen werden nicht übertragen (bewusst, um Versehen nicht zu multiplizieren).
  • Umbenennen einer Kür wirkt wie „neu lokal“ + „nur Cloud“: beide Fassungen landen nebeneinander.
  • Sehr große Kürsammlungen werden vollständig verglichen; für hunderte Dateien ist das noch unkritisch, für tausende wäre ein Manifest sinnvoll.
  • Dropbox-Uploads sind auf 150 MB pro Datei begrenzt (App-Ordner-Apps). Für Kür-JSONs und übliche Musikdateien reicht das; größere Dateien müssten chunked hochgeladen werden.
  • Google Drive erlaubt technisch mehrere Dateien mit demselben Namen. Der Sync sucht die erste passende Datei und führt bestehende Duplikate aus anderen Quellen nicht zusammen.

Migration vom FTP-Sync

Der frühere FTP-/FTPS-Sync ist entfernt. Alte user://sync.cfg-Einträge (host, port, user, password, ftps, verify_certificate) werden ignoriert; beim ersten Öffnen der Sync-Einstellungen muss ein Cloud-Konto verbunden werden. Die Dateien im alten FTP-Verzeichnis werden nicht automatisch übernommen: Wer sie behalten will, kopiert sie einmalig manuell in den Cloud-Ordner oder verbindet beide Geräte mit demselben Cloud-Konto und lädt die lokalen Kürdateien hoch.