- zentrales Sport-Theme für das Weißbrett - Küren im Sync umbenennen, löschen und Musikzuordnung aufräumen - Konfliktbereinigung mit Vorschau und gezieltem Löschen - Sync nutzt saved_at aus der Kür statt Gerätezeit - Schrittsequenzen über Mehrfachauswahl gruppieren - Startskript aktualisiert den class_name-Cache bei Änderungen
199 lines
11 KiB
Markdown
199 lines
11 KiB
Markdown
# 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. Es gibt kein Konto auf einem
|
||
Rinkplanner-Server. Jeder Nutzer verbindet sein eigenes Konto; die App
|
||
speichert nur den Refresh-Token lokal auf dem Gerät.
|
||
|
||
## 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.
|