feat: Cloud-Sync über Dropbox und Google Drive

- FTP-Sync durch Cloud-Backends ersetzt (Dropbox, Google Drive)
- OAuth-Flow mit nutzereigenen Tokens und App-Key-Konfiguration
- Zeit-Tooltips für Timeline-Labels und Abschnittsbanner beim Playback
- Tests, Build-Konfiguration und Doku aktualisiert
This commit is contained in:
torsten 2026-11-09 06:25:21 +01:00
parent 533a12ef1a
commit 74d9d6b61f
36 changed files with 3040 additions and 817 deletions

View file

@ -1,35 +1,41 @@
# Kontosync über FTP
# Kür-Sync über Cloud-Speicher
Der Abgleich zwischen Desktop und Tablet läuft **manuell** über einen
FTP-Zugang. Es gibt kein Konto im Sinne einer Anmeldung auf einem Server:
Die Zugangsdaten sind das „Konto“, jedes Gerät bekommt dieselben Daten.
Der Abgleich zwischen Desktop und Tablet läuft **manuell** über den eigenen
Cloud-Speicher des Nutzers: Google Drive oder Dropbox. 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. Eintragen:
- **Server** – Hostname des FTP-Servers (ohne `ftp://`)
- **Port** – normalerweise 21
- **Benutzer / Passwort**
- **Verzeichnis** – Zielordner relativ zum Login, z. B. `rinkplanner`
3. **FTPS** eingeschaltet lassen (empfohlen).
4. **Server-Zertifikat prüfen** nur abschalten, wenn der Hoster ein
abweichendes Zertifikat nutzt (bei Shared Hosting häufig). Die Verbindung
bleibt verschlüsselt, der Server wird dann aber nicht kryptografisch
bestätigt.
2. **Anbieter** wählen: Dropbox oder Google Drive.
3. **Verbinden…** drücken und im Browser mit dem eigenen Konto anmelden:
- **Google Drive:** Die App zeigt einen Code und öffnet die
Google-Anmeldeseite. Nach der Bestätigung im Browser schließt sich der
Dialog automatisch.
- **Dropbox:** Die App öffnet die Dropbox-Seite. Den dort angezeigten Code
in das Feld einfügen und **Verbinden** drücken.
4. **Cloud-Ordner** festlegen. Bei Dropbox ist das standardmäßig der
App-Ordner selbst (`Apps/<App-Name>`); bei Google Drive legt die App
standardmäßig den Ordner `Rinkplanner` an. Ein leerer Eintrag bedeutet
„Cloud-Hauptordner des Anbieters“.
5. **Speichern**.
Danach **Datei → Jetzt synchronisieren**.
Auf dem Tablet muss das Konto ebenfalls einmal verbunden werden. Beide Geräte
können dasselbe Google-/Dropbox-Konto verwenden; der Abgleich läuft über den
gemeinsamen Cloud-Ordner.
## Was passiert
- Jede Kür liegt als `.json` unter `user://routines/` und wird 1:1 in das
FTP-Verzeichnis 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 Serverkopien nicht verlieren; neue Speicherungen schreiben `.json`.
Beim Laden wird eine `.tres` vor dem `ResourceLoader` gegen eine Whitelist
- Jede Kür liegt als `.json` unter `user://routines/` und wird 1:1 in den
Cloud-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:
@ -37,12 +43,12 @@ Danach **Datei → Jetzt synchronisieren**.
| Lage | Aktion |
| :--- | :--- |
| nur lokal, noch nie synchronisiert | hochladen |
| nur auf dem Server | herunterladen |
| nur in der Cloud | herunterladen |
| seit dem letzten Sync nur lokal geändert | hochladen |
| seit dem letzten Sync nur auf dem Server geändert | herunterladen |
| beidseitig geändert (seit dem letzten Sync) | **Konflikt**: lokale Fassung bleibt Hauptdatei, Serverfassung kommt als `(Server …)`-Kopie dazu |
| seit dem letzten Sync nur in der Cloud geändert | herunterladen |
| beidseitig geändert (seit dem letzten Sync) | **Konflikt**: lokale Fassung bleibt Hauptdatei, Cloud-Fassung kommt als `(Server …)`-Kopie dazu |
| Datei auf einer Seite gelöscht | nichts tun (keine Löschweitergabe) |
| erster Sync, Datei auf beiden Seiten | **Server übernimmt**: Serverfassung wird Hauptdatei, lokale Fassung bleibt als `(Lokal …)`-Kopie |
| erster Sync, Datei auf beiden Seiten | **Cloud übernimmt**: Cloud-Fassung wird Hauptdatei, lokale Fassung bleibt als `(Lokal …)`-Kopie |
### Wie kommt eine Kür vom Desktop aufs Tablet?
@ -55,11 +61,11 @@ Kür-Titel entsteht). Eine Kür mit demselben Namen auf beiden Geräten ist
kein „Update“, sondern eine Kollision:
- **Erster Sync einer Datei auf beiden Seiten** (kein gemeinsamer Stand):
Die **Serverfassung übernimmt den Namen**, die lokale Fassung bleibt als
Die **Cloud-Fassung übernimmt den Namen**, die lokale Fassung bleibt als
`name (Lokal JJJJ-MM-TT HHMM).json` daneben. So bekommt ein neues Gerät die
gemeinsame Version, ohne die lokale Arbeit zu verlieren.
- **Beide Seiten seit dem letzten Sync geändert**: Die lokale Fassung bleibt
Hauptdatei, die Serverfassung kommt als
Hauptdatei, die Cloud-Fassung kommt als
`name (Server JJJJ-MM-TT HHMM).json` dazu. Beim nächsten Sync wird diese
Kopie als neue Kür hochgeladen. Zusammenführen musst du selbst.
Die Kopien behalten die Endung der Ausgangsdatei; bei Legacy-`.tres`
@ -81,20 +87,27 @@ Kür öffnen und bearbeiten.
| Datei | Aufgabe |
| :--- | :--- |
| `src/core/sync/ftp_client.gd` | FTP/FTPS-Client (USER/PASS, AUTH TLS + PROT P, EPSV/PASV, MLSD, SIZE, RETR, STOR, DELE, MKD, RNFR/RNTO) |
| `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, Konfliktnamen, Zeitstempel |
| `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`.
- Uploads gehen zuerst nach `name.uploading` und werden dann umbenannt
(falls der Server das verweigert: direkter Upload).
- 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 präparierter
Server kann damit keine eingebetteten GDScripts ausführen.
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 auf Server und Tablet nicht verschwinden.
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
@ -102,22 +115,30 @@ Kür öffnen und bearbeiten.
behalten die Audio-Endung (z. B. `kuer (Server …).mp3`).
- Eigene Timeline-Labels stehen in der Kür-JSON (`timeline_labels`) und
werden ohne Zusatzdateien mit der Kür übertragen.
- Zugangsdaten liegen in `user://sync.cfg` (Klartext, app-privat). Auf
- 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/`.
`~/.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.
## Erfahrungen mit dem Zielserver
## Datenschutz und Musiklizenzen
- Der Server spricht explizites FTPS (`AUTH TLS`), außerdem `MLST`, `MDTM`,
`MFMT` und `EPSV` – genau das, was der Abgleich braucht.
- Sein TLS-Zertifikat passt nicht zum Hostnamen (leeres CN/SAN). Deshalb muss
„Server-Zertifikat prüfen“ ausgeschaltet werden; die Übertragung bleibt
verschlüsselt.
- Der Zielordner existiert in Kleinschreibung. Die App wechselt direkt
hinein und legt ihn bei Bedarf per `MKD` an.
- Ein vollständiger Testlauf (Upload, Überspringen, Download, Übernahme,
Konflikt, Aufräumen) lief gegen den echten Server erfolgreich.
- 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
@ -126,7 +147,23 @@ Kür öffnen und bearbeiten.
verhindert dann Datenverlust, nicht aber doppelte Dateien.
- Löschungen werden nicht übertragen (bewusst, um Versehen nicht zu
multiplizieren).
- Umbenennen einer Kür wirkt wie „neu lokal“ + „nur Server“: beide Fassungen
- 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.