rinkplanner/docs/sync.md
torsten f553785710 feat: manuellen FTP-Sync zwischen Desktop und Tablet
- FTP/FTPS-Client (USER/PASS, AUTH TLS + PROT P, EPSV/PASV, MLSD, SIZE,
  RETR, STOR, DELE, MKD, RNFR/RNTO) ohne externe Bibliothek
- Sync-Vergleich pro Kürdatei mit lokalem Sync-Stand: hochladen,
  herunterladen, überspringen; beidseitige Änderungen bleiben als Kopie
  mit Server-Zeitstempel erhalten, die lokale Fassung wird nie verworfen
- Sync-Einstellungen (Host, Port, Benutzer, Passwort, Verzeichnis, FTPS,
  Zertifikatsprüfung) unter user://sync.cfg, nicht im Repository
- Sync läuft im Thread, Fortschritt in der Statusleiste, Zusammenfassung
  im Dialog; geöffnete Kür wird nur unverändert neu geladen
- Atomare Ersetzung über .part/.bak, Uploads über .uploading + Umbenennen
- Tests für Vergleichsregeln, Konfliktnamen, PASV/EPSV/MDTM, Sync-Stand
  und Einstellungs-Dialog; zusätzlich E2E gegen den echten FTP-Server
- docs/sync.md mit Einrichtung, Verhalten und Grenzen
2026-10-30 11:03:18 +01:00

80 lines
3.7 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.

# Kontosync über FTP
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.
## 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.
5. **Speichern**.
Danach **Datei → Jetzt synchronisieren**.
## Was passiert
- Jede Kür liegt als `.tres` unter `user://routines/` und wird 1:1 in das
FTP-Verzeichnis gespiegelt (flach, keine Unterordner).
- 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 auf dem Server | herunterladen |
| seit dem letzten Sync nur lokal geändert | hochladen |
| seit dem letzten Sync nur auf dem Server geändert | herunterladen |
| beidseitig geändert | **Konflikt**: beide Fassungen behalten |
| Datei auf einer Seite gelöscht | nichts tun (keine Löschweitergabe) |
| erster Sync, Datei auf beiden Seiten | **Konflikt** (kein Stand bekannt) |
- Bei einem Konflikt bleibt die lokale Fassung unverändert; die Serverfassung
wird als `name (Server JJJJ-MM-TT HHMM).tres` daneben gespeichert. Beim
nächsten Sync wird diese Kopie als neue Kür hochgeladen. Zusammenführen
musst du selbst.
- 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 / 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/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/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).
- Downloads landen in `name.part` und ersetzen die Zieldatei erst danach.
- Zugangsdaten 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/`.
- Android braucht die `INTERNET`-Berechtigung – ist im APK gesetzt.
## Grenzen
- Kein automatischer Sync, kein Push, kein Locking. Zwei Geräte, die
gleichzeitig synchronisieren, können sich überholen; der Konfliktfall
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
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.