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

203 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`](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`](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.