Melo/docs/superpowers/specs/2026-08-27-sync-ausbau-design.md

# Sync-Ausbau: Auswahl-Upload, Einzel-Song-Offline, Merge-Fixes, Echtzeit

Status: Approved (Dustin, 2026-08-27) — vor dem Implementierungsplan noch
durchs agent-review-panel (Pflicht-Workflow).

## Kontext

Die Melo-App synchronisiert heute schon Musikdateien UND Metadaten mit der
Melo-Cloud (`cloud.baka-net.de` → `melo_cloud.py`, Bearer-JWT via
`BakaAuth`): `SyncService` lädt lokale Songs ohne Cloud-ID automatisch
hoch (Multipart, 50 MB-Grenze, Server-Dedup per sha256 +
Akustik-Fingerprint), lädt neue Server-Songs herunter, zieht Tombstones
in beide Richtungen nach (mit Lösch-Bremse) und läuft automatisch bei
App-Start/Resume (15-Minuten-Drossel) mit Fortschrittsanzeige in den
Einstellungen. Der Server hardlinkt jede hochgeladene Datei aktiv nach
`/home/dustin/navidrome/music` und stößt einen Navidrome-Scan an — der
Weg Handy→Server→Navidrome-Bibliothek existiert also bereits vollständig.
`DownloadService` kann ganze Alben/Künstler in den App-Speicher offline
nehmen (Fortschritt + Abbrechen), dazu gibt es einen automatischen
2-GB-Abspiel-Cache.

Diese Spec schließt die verbliebenen Lücken (Auftrag Dustin, 2026-08-26,
im Brainstorming zerlegt und entschieden):

| Entscheidung | Ergebnis |
|---|---|
| Zerlegung | Erst Sync-Ausbau (diese Spec, Android), Cross-Platform Mac+Windows als **eigenes späteres Projekt** |
| Upload-UX | Bestehenden Auswahl-Modus in „Meine Musik“ um „Auf den Server laden“ erweitern; Auto-Upload beim Sync bleibt |
| Umfang | Einzel-Song-Offline + Playlist-Sync + Fortschritts-Notification/Sync-Bericht + Echtzeit-SSE; Favoriten-Merge-Fix immer dabei |
| Playlist-Konflikte | Vereinigung (Union) wie bei Favoriten; Reihenfolge: längerer Stand gewinnt |
| Bau-Ansatz | Ansatz 1: inkrementeller Ausbau des bestehenden `SyncService`, neue Logik in kleinen separaten Einheiten |

## Ziele

1. **Favoriten-Merge-Fix** (Datenverlust-Bug): kein Gerät überschreibt
   mehr die Server-Favoriten mit seinem lokalen Stand.
2. **Gezielter Upload**: einzelne Songs im Auswahl-Modus markieren und
   hochladen.
3. **Einzel-Song-Offline**: einzelne Server-Titel offline nehmen, nicht
   nur ganze Alben/Künstler.
4. **Playlist-Sync**: Playlisten beidseitig mit der Melo-Cloud abgleichen.
5. **Sichtbarkeit**: persistente Sync-Notification + „Was ist neu“-Bericht.
6. **Echtzeit**: Änderungen anderer Geräte in Sekunden statt bis zu 15
   Minuten (SSE), Poll bleibt Fallback.

## Nicht-Ziele

- **Kein Cross-Platform** (Mac/Windows) — eigenes Folgeprojekt.
  `windows/`/`linux/` existieren nicht, `just_audio` hat kein
  Windows-Backend; das ist Plattform-Infrastruktur, keine Sync-Logik.
- **Kein Delta-Protokoll** (`/sync?since=…`): bei ~330 Songs auf dem
  Server ist die Voll-Liste billig; der Delta-Endpunkt deckt zudem nur
  Songs ab, nicht Favoriten/Playlisten. YAGNI.
- **Kein Hintergrund-Sync** (WorkManager o. ä.): Sync weiterhin nur bei
  geöffneter App (Start/Resume/SSE/manuell) — wie bisher und wie in v2.
- **Keine Playlist-Tombstones auf dem Server**: offline gelöschte
  Playlisten kommen beim nächsten Sync zurück (bekannte Einschränkung,
  siehe unten) — ein Server-Tombstone-System wäre ein eigener Auftrag.
- **Kein Chunked/Resumable Upload**: 50-MB-Dateien am Stück wie bisher.

## Architektur

Rückgrat bleibt `SyncService` (`lib/services/sync_service.dart`) +
`MeloCloudService` (`lib/services/melo_cloud_service.dart`). Neu:

| Einheit | Datei | Verantwortung |
|---|---|---|
| Merge-Logik | `lib/services/sync_merge.dart` (neu) | Reine Funktionen ohne I/O: `favoritenVereinigung`, `playlistVereinigung`, Playlist-Zuordnung per Name. Voll unit-testbar. |
| Benachrichtigung | `lib/services/sync_benachrichtigung.dart` (neu) | Dünner Wrapper um `flutter_local_notifications` + reine Entscheidungslogik (wann zeigen/aktualisieren/Bericht fällig). |
| Echtzeit | `lib/services/echtzeit_sync.dart` (neu) | SSE-Verbindung zu `GET /subscribe`, Event-Parser, Debounce, Reconnect-Backoff, Lifecycle-Anbindung. |
| Cloud-Erweiterung | `melo_cloud_service.dart` (erweitert) | Playlisten-CRUD, Favoriten-Toggle, SSE-Stream öffnen. |
| Sync-Erweiterung | `sync_service.dart` (erweitert) | Zwei neue Phasen (Favoriten-Union, Playlist-Union), `ladeAusgewaehlteHoch`, Drossel-Umgehung für SSE. |
| UI | bestehende Screens | Auswahl-Modus-Aktion, Einzel-Song-Offline-Knopf, Bericht-Dialog. |

Neue Abhängigkeit: **`flutter_local_notifications`** (die einzige neue
Dependency dieser Spec).

## Feature-Details

### 1. Favoriten-Merge (Datenverlust-Fix)

Heutiger Bug: `_gleicheFavoritenAb()` (sync_service.dart) POSTet die
lokale Favoritenliste als Komplett-Ersatz — ein frisch installiertes
Gerät löscht damit beim ersten Sync alle Server-Favoriten.

Neu, zwei Mechanismen (Vorbild Melo v2):

- **Sofort-Push beim Antippen:** `PlaylistService.toggleFavorite` schickt
  online zusätzlich fire-and-forget ein deterministisches
  `set:true/false` an den Server (Endpunkt `POST /favorites/toggle` mit
  set-Parameter existiert in melo_cloud.py). Deterministisch statt
  Toggle, damit ein abweichender Server-Zustand den Wunsch nie
  invertiert. Nur für Songs mit cloudId; Fehler werden still geschluckt
  (der nächste Voll-Sync korrigiert).
- **Vereinigung beim Sync:** neue Phase in `synchronisiere()`:
  1. `GET /favorites` (der bereits implementierte, bisher ungenutzte
     `MeloCloudService.favoriten()`).
  2. `favoritenVereinigung(lokal, server)` (sync_merge.dart): Union über
     cloudIds.
  3. Ergebnis als `POST /favorites` zum Server UND lokal übernehmen
     (fehlende Favoriten lokal setzen).
- **Sicherheitsregel (hart):** Schlägt das GET fehl, wird die gesamte
  Phase übersprungen — es wird NIE ohne vorheriges erfolgreiches GET
  gePOSTet. Genau das ist der heutige Bug; er darf durch keinen
  Fehlerpfad wieder entstehen.
- Songs ohne cloudId: bleiben lokal-only, tauchen in keiner Richtung im
  Abgleich auf.
- Semantik der Union: Ent-Favorisierungen propagieren über den
  Sofort-Push (online) — die Sync-Union gleicht nur Hinzufügungen ab.
  Offline entfernte Herzen kommen beim nächsten Sync zurück, wenn kein
  Online-Push sie vorher gemeldet hat. Das ist dieselbe bewusste
  v2-Semantik (kein Datenverlust > perfekte Lösch-Propagation).

### 2. Playlist-Sync

- **Drift-Migration:** Tabelle `Playlists` bekommt `cloudId TEXT NULL`.
  (Schema-Version erhöhen, Migration schreiben + testen.)
- **Zuordnung:** Playlisten mit cloudId sind eindeutig verbunden. Ohne
  cloudId: einmalige Zuordnung per Namensvergleich (case-insensitive,
  getrimmt); Treffer bekommt die Server-cloudId persistiert. Lokale
  Playlist ohne Server-Gegenstück → auf dem Server anlegen
  (`POST /playlists`), cloudId übernehmen. Server-Playlist ohne lokales
  Gegenstück → lokal anlegen.
- **Song-Vereinigung:** `playlistVereinigung(lokal, server)` — Union der
  Songs per Song-cloudId. Reihenfolge: der längere Stand liefert die
  Grundreihenfolge, nur auf der jeweils anderen Seite vorhandene Songs
  werden hinten angehängt. Ergebnis geht an Server
  (Playlist-Songs-Endpunkt) und in die lokale DB.
- **Sofort-Push online:** Playlist anlegen/umbenennen/löschen sowie
  Song hinzufügen/entfernen werden bei bestehender Verbindung
  fire-and-forget direkt zum Server durchgereicht (Endpunkte existieren:
  Playlists-CRUD + songs + positions).
- **Songs ohne cloudId** in einer Playlist: bleiben lokal in der
  Playlist, werden zum Server einfach nicht mitgemeldet — kein Fehler.
- **Bekannte Einschränkung (dokumentiert, akzeptiert):** Der Server hat
  keine Playlist-Tombstones (Löschen = hartes DELETE). Eine OFFLINE
  gelöschte Playlist kommt beim nächsten Sync vom Server zurück.
  Online-Löschungen greifen sofort und dauerhaft. Falls das in der
  Praxis stört: Server-Tombstones als separater Auftrag an
  Hermes/claude-server.

### 3. Upload-Auswahl („Auf den Server laden“)

- Auswahl-Modus in „Meine Musik“ (existiert, siehe
  `auswahl_modus_test.dart`) bekommt die Aktion **„Auf den Server
  laden“**.
- Neue Methode `SyncService.ladeAusgewaehlteHoch(List<Song> songs)`:
  nutzt den bestehenden `_ladeHoch`-Pfad pro Song, mit Fortschritt über
  die bestehenden Felder (`laeuft/erledigt/gesamt/status`) und der neuen
  Notification.
- Songs, die schon eine cloudId haben, werden übersprungen; zu große
  Dateien (>50 MB) einzeln als Fehler vermerkt, der Rest läuft weiter.
  Ergebnis-Meldung im Stil „3 hochgeladen, 2 waren schon da, 1 zu groß“.
- Läuft bereits ein Sync, wird die Aktion abgewiesen („Sync läuft
  gerade“) — der bestehende Doppel-Lauf-Schutz des SyncService gilt.
- Der automatische Voll-Upload beim Sync (alles ohne cloudId) bleibt
  unverändert bestehen.

### 4. Einzel-Song-Offline

- `DownloadService` bekommt `ladeEinzelnenTitel(SubsonicSong song)` —
  der interne Pro-Song-Lade-Loop existiert bereits (Album-Pfad), wird
  nur als Einzel-API zugänglich. Gleiche Ablage (App-Speicher,
  Application-Support/melo_downloads), gleiche Buchführung
  (Downloads-Tabelle per navidromeId), gleiche Fehlerbehandlung.
- UI: Songzeilen in der Server-Album-/Künstler-Ansicht
  (`server_titel_screen.dart`) bekommen den Lade-Knopf, den es heute nur
  pro Album gibt (Muster `_LadeKnopf`), inklusive Zustand
  „schon offline“ mit Entfernen-Option (bestehendes
  `DownloadService.entferne`).

### 5. Fortschritts-Notification + Sync-Bericht

- **`SyncBenachrichtigung`** (Wrapper um `flutter_local_notifications`,
  eigener Channel z. B. `de.baka.melo.sync`):
  - Während `SyncService.laeuft`: persistente (ongoing) Notification
    „Synchronisiere… X/Y“ mit Fortschrittsbalken, aktualisiert über die
    bestehenden ChangeNotifier-Felder.
  - Bei Abschluss: kurze Erfolgs-Notification (bzw. Fehlertext), nicht
    persistent, tippbar → App öffnen.
  - Benachrichtigungs-Berechtigung wird seit dem Berechtigungs-Feature
    beim App-Start angefragt; verweigert → stiller Verzicht, die
    In-App-Anzeige in den Einstellungen bleibt wie heute.
  - Die ENTSCHEIDUNGEN (wann zeigen, wann aktualisieren, wann Bericht
    fällig) liegen als reine Funktionen in derselben Datei und sind ohne
    Plattform-Kanäle testbar; der Plugin-Aufruf selbst bleibt dünn.
- **Sync-Bericht („Was ist neu“):** Ist der letzte erfolgreiche Sync
  >24 h her, sammelt der nächste Sync Zähler (neue Songs, gelöschte,
  Favoriten geändert, Playlisten geändert) und zeigt danach einmalig
  einen Dialog (v2-Parität „Willkommen zurück!“). Stand in
  SharedPreferences.

### 6. Echtzeit per SSE

- **`EchtzeitSync`**: öffnet im Vordergrund `GET /subscribe`
  (Bearer-Header; `http`-Paket, `client.send()` → StreamedResponse,
  zeilenweises SSE-Parsing — keine neue Dependency). Server schickt
  Heartbeat alle 30 s.
- Events (`song_delete`, `song_update`, `song_favorite` + das neue
  Upload-Event, s. u.): 3 s Debounce (Bursts bündeln), dann
  `SyncService.synchronisiere()` mit neuem Parameter
  `erzwinge: true`, der die 15-Minuten-Drossel (`sollAutoSync`) umgeht.
  Der Event-INHALT wird bewusst nicht einzeln angewendet — ein
  angestoßener Voll-Sync ist robuster als Event-Replays (Events sind
  serverseitig lückenhaft, siehe Bestandsaufnahme).
- Lifecycle: verbinden bei `resumed`, trennen bei `paused` (kein
  Hintergrund-Socket, kein Akku-Fresser).
- Verbindungsabriss → Reconnect mit exponentiellem Backoff (Start 5 s,
  Deckel 5 min). SSE komplett tot → App verhält sich exakt wie heute
  (Poll bei Start/Resume).
- **Server-Auftrag (separat, an Hermes/claude-server — nicht Teil des
  App-Plans):** `melo_cloud.py` feuert beim Upload bisher KEIN
  SSE-Event (`_emit_event` fehlt in `upload()`); ein `song_upload`-Event
  ergänzen. Die App funktioniert auch ohne (Poll-Fallback), aber
  „neuer Song erscheint in Sekunden auf dem anderen Gerät“ braucht es.

## Sync-Phasen nach Ausbau (Reihenfolge)

1. Tombstones nachziehen (bestehend)
2. Neue Server-Songs herunterladen (bestehend)
3. Lokale Songs ohne cloudId hochladen (bestehend)
4. **Favoriten-Vereinigung (neu)**
5. **Playlist-Vereinigung (neu)**
6. Verlauf melden (bestehend)
7. Zeitstempel + ggf. Bericht (erweitert)

## Fehlerfälle

- Favoriten-GET scheitert → Phase 4 komplett überspringen (nie blind
  POSTen), Sync läuft weiter.
- Playlist-Endpunkt scheitert → Phase 5 überspringen, Sync läuft weiter.
- Auswahl-Upload: Datei >50 MB oder Einzel-Upload-Fehler → im Ergebnis
  vermerken, mit nächstem Song fortfahren.
- Einzel-Song-Offline: wie bestehender Album-Pfad (Fehler pro Titel,
  kein Abbruch des Rests).
- SSE nicht erreichbar/abgerissen → Backoff-Reconnect, still; kein
  Nutzer-Fehler, Poll bleibt.
- Notification-Berechtigung verweigert → In-App-Fortschritt wie heute.
- Sync bereits aktiv → Auswahl-Upload/SSE-Anstoß werden abgewiesen bzw.
  verzögert (bestehender Schutz).

## Risiken (aus der Bestandsaufnahme, im Plan zu beachten)

- Die Lösch-Bremse bremst nur Server-Löschungen; lokale Tombstones
  laufen ungebremst — beim Ausbau nicht verschlimmern.
- Uploads/Downloads liegen serverseitig komplett im RAM — der
  Auswahl-Upload bleibt sequenziell (kein Parallel-Upload), um den
  Server nicht aufzublähen.
- v2-Lektionen übernehmen: Sync-Zeitstempel = Snapshot VOR dem Listen
  (Tombstone-Race), neue Server-Songs sofort MIT cloudId in die DB
  (Doppel-Download-Falle), Dateinamen-Kollisionszähler.
- `POST /favorites` bleibt technisch ein Voll-Ersatz — die Sicherheit
  liegt allein in der GET-vor-POST-Regel. Tests müssen genau diesen
  Pfad absichern.

## Tests

- `sync_merge.dart`: Unit-Tests für Favoriten-Union (leer×leer,
  einseitig, disjunkt, Songs ohne cloudId), Playlist-Union
  (Reihenfolge-Regel, Erst-Zuordnung per Name, Groß/Kleinschreibung,
  Namens-Kollision), deterministisch, ohne I/O.
- `echtzeit_sync.dart`: SSE-Zeilen-Parser (event/data/Heartbeat/
  Fragmentierung), Debounce- und Backoff-Entscheidungen als reine
  Funktionen.
- `sync_service.dart`: neue Phasen mit MockClient (inkl. GET-Fehler →
  kein POST; Auswahl-Upload mit Mischung aus ok/zu groß/schon da).
- `sync_benachrichtigung.dart`: Entscheidungslogik (zeigen/aktualisieren/
  Bericht fällig) pur; Plugin-Aufrufe nicht getestet (dünner Wrapper).
- Widget-Tests: Auswahl-Modus-Aktion sichtbar + ruft Upload auf;
  Einzel-Song-Knopf lädt/entfernt; Bericht-Dialog erscheint nach
  >24h-Marke.
- Drift-Migration: Test, dass Bestandsdaten die neue Spalte überleben.

## Offene Abhängigkeiten

1. **Server: `song_upload`-SSE-Event** in `melo_cloud.py` (Hermes /
   claude-server) — App funktioniert ohne, Echtzeit für neue Songs
   braucht es.
2. Optional/nachrangig (nur falls Praxisproblem): Playlist-Tombstones
   serverseitig.