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

Sync-Ausbau: Favoriten-Fix, Auswahl-Upload, Einzel-Song-Offline, Playlist-Sicherung

Status: Nachgeschärft nach agent-review-panel (Urteil Phase 14, 2026-08-27: Score 6/10, Verdikt „Spec nachschärfen dann freigeben"). Alle 17 Aktionspunkte A1–A17 sind eingearbeitet. Bedingung des Richters: diese Fassung wird einmal kurz gegengelesen, bevor der Implementierungsplan entsteht — A1, A5 und A7 ändern, was gebaut wird, nicht nur wie es beschrieben ist.

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 und er läuft auch rückwärts: verschwindet die lokale Datei, meldet der Sync die Löschung, und der Server entfernt die Audiodatei aus Registry und Navidrome-Bibliothek (Details unter §Risiken, „Irreversibler Löschpfad"). DownloadService kann ganze Alben/Künstler in den App-Speicher offline nehmen (Fortschritt + Abbrechen), dazu gibt es einen automatischen Abspiel-Cache (Standard 2 GB, einstellbar 0–8192 MB; app_settings.dart:28, :31).

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 (durch Review überholt — siehe unten)
Playlist-Konflikte	Vereinigung (Union) wie bei Favoriten; Reihenfolge: längerer Stand gewinnt (durch Review überholt — siehe unten)
Bau-Ansatz	Ansatz 1: inkrementeller Ausbau des bestehenden SyncService, neue Logik in kleinen separaten Einheiten

Die Tabelle gibt den Stand des Brainstormings wieder — die Zeilen „Umfang" und „Playlist-Konflikte" sind durch das Review überholt, die Korrektur steht direkt darunter.

Was das Review daran geändert hat (die Zerlegung, die Upload-UX und der Bau-Ansatz bleiben unangetastet):

• Der Umfang schrumpft: SSE und die persistente Notification werden eigene spätere Stufen (§Spätere Stufen), Playlist-Sync wird auf eine einseitige Sicherung reduziert.
• Die Union-Semantik bei Favoriten bleibt genau wie entschieden — nur der Schreibweg wechselt vom Voll-Ersatz auf additive Pushes (A1). Das ist keine Überstimmung der Auftraggeber-Entscheidung, sondern ihre Präzisierung.
• Die Playlist-Konfliktregel („längerer Stand gewinnt") entfällt ersatzlos, weil es ohne Rück-Merge keinen Konflikt mehr gibt (A5).

OFFENE ENTSCHEIDUNG — Rückfrage an Dustin (noch nicht beantwortet)

Ist der irreversible Löschpfad gewollt? Verschwindet eine lokale Datei (SD-Karte nicht eingehängt, Berechtigung entzogen, Dateimanager), löscht der Sync sie auf dem Server — und damit auch aus der Navidrome-Bibliothek. Erneutes Hochladen repariert das nachweislich nicht. Die technische Kette steht vollständig belegt unter §Risiken → „Irreversibler Löschpfad".

• Antwort „ja, gewollt“ → es ist eine dokumentierte Eigenschaft, nichts weiter zu tun.
• Antwort „nein“ → ein Server-Auftrag (Dedup-Zweig stellt die Datei wieder her, wenn registry_pfad(sid) leer ist) gehört vor Feature 3.

Kein Reviewer kann das entscheiden — es ist eine Produktfrage. Stand: unbeantwortet. Die Reihenfolge in §Reihenfolge ist bewusst so gewählt, dass mit Stufe 1 begonnen werden kann, ohne dass die Antwort vorliegt.

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-Sicherung: lokale Playlisten überleben ein zurückgesetztes Handy (einseitig, siehe Feature 2).
5. Sichtbarkeit: „Was ist neu“-Bericht als In-App-Dialog.

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/manuell) — wie bisher und wie in v2.
• Kein Chunked/Resumable Upload: 50-MB-Dateien am Stück wie bisher.
• Kein Echtzeit-Sync (SSE) in dieser Stufe. Der beworbene Haupt-Nutzen („neuer Song erscheint in Sekunden auf dem anderen Gerät") hängt am song_upload-Event, das melo_cloud.py heute nicht feuert (_emit_event nur bei :393, :410, :687) und das diese Spec ausdrücklich auslagert — am Auslieferungstag könnte SSE also genau das nicht, wofür es gebaut wird. Die drei vorhandenen Kanäle (song_delete, song_update, song_favorite) haben heute keinen Adressaten (Live-Stand: ein Nutzer mit Songs, 0 gelöschte, 0 Favoriten, 0 Playlisten). Dem stehen acht eigene Fehlerklassen gegenüber: eigener http.Client (der geteilte aus melo_cloud_service.dart:82-83 würde beim close() laufende Sync-Requests mitreißen), Heartbeat-Watchdog gegen den halboffenen Socket nach WLAN↔LTE, dauerhafter 401-Ausstieg (baka_auth.dart hat kein Refresh), Selbst-Echo-Unterdrückung (melo_realtime.py:56-70 broadcastet an alle Queues des Nutzers ohne Absenderkennung), Timer-Abbau bei paused, Debounce, Backoff, Nachhol-Anstoß. Ehrlicher Preis: Änderungen anderer Geräte erscheinen beim nächsten App-Start oder Zurückkehren — genau wie heute. Es gibt keinen billigeren Poll-Ersatz: automatisch() läuft nur aus initState und resumed (main.dart:175, :203), ein Timer existiert nicht.
• Keine persistente Fortschritts-Notification in dieser Stufe — sie ist die einzige Quelle einer neuen Dependency und wird eigene Stufe (§Spätere Stufen, Stufe B).
• Kein beidseitiger Playlist-Merge — eigene, spätere Spec (A5).
• Keine Playlist-Tombstones auf dem Server: ein Server-Tombstone-System wäre ein eigener Auftrag.
• Kein Rollback auf eine ältere App-Version nach der Schema-Migration: database.dart:154-192 kennt nur onCreate und onUpgrade.

Spätere Stufen (bewusst nach hinten geschoben, nicht verworfen)

Stufe	Inhalt	Vorbedingung
Notification Stufe B	persistente Fortschritts-Notification via flutter_local_notifications	grüner Beweis-Build (siehe unten)
SSE	Echtzeit-Sync, eigene Spec	song_upload-Event steht in melo_cloud.py
Playlist-Merge	beidseitiger Abgleich, eigene Spec	Rename-Endpunkt + Tombstones serverseitig
Basis-Snapshot	verlässliche Lösch-Propagation bei Favoriten	erst wenn die additive Semantik in der Praxis stört

Notification Stufe B, Details (eigenes Arbeitspaket): Sie erzwingt flutter_local_notifications und damit isCoreLibraryDesugaringEnabled = true plus coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4") in android/app/build.gradle.kts — die Datei hat heute überhaupt keinen dependencies { }-Block, der Gradle-Heap steht auf 2 GB (gradle.properties:1, dokumentierte OOM-Quelle), AGP ist 9.0.1 (settings.gradle.kts:22) und android-37 ist ein Nachbau von 36. Erstes Abnahmekriterium der Stufe B ist ein grüner flutter build apk --target-platform android-arm64 nach dem pub add — vor jeder Zeile Notification-Logik. multiDexEnabled entfällt aus der Forderung: bei minSdkVersion = 24 (FlutterExtension.kt:26) ist es gegenstandslos. Mitzuentscheiden: Channel mit Importance.low, onlyAlertOnce: true, und ein cancel() beim Init gegen die nach App-Kill stehengebliebene Fortschritts-Notification.

SSE später: Die acht Härtungs-Bausteine gehören dann in jene Spec, nicht in einen Plan zu dieser. Vorbedingung außerdem: der additive Delta-Push (Feature 1) feuert je gepushtem Favoriten ein song_favorite-Event (melo_cloud.py:687) — beim ersten Lauf nach der Umstellung also so viele Events wie lokale Favoriten. Ohne SSE ist das folgenlos; kommt SSE, muss die Selbst-Echo-Unterdrückung vorher stehen.

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: fehlendeFavoriten (Mengendifferenz beider Richtungen), berichtFaellig. Voll unit-testbar.
Cloud-Erweiterung	melo_cloud_service.dart (erweitert)	setzeFavorit(cloudId, set) (neu, deterministisch), Playlisten-CRUD; parseFavoriten gehärtet.
Sync-Erweiterung	sync_service.dart (erweitert)	Neue Phase (additiver Favoriten-Abgleich), ladeAusgewaehlteHoch, abbrechen(), Phasen-Isolation, Erfolgs-Flag.
UI	bestehende Screens	Auswahl-Modus-Aktion, Einzel-Song-Offline-Knopf, Bericht-Dialog.

Neue Abhängigkeit: keine. Das war in der Vorfassung flutter_local_notifications und damit der einzige harte Build-Blocker der ganzen Planung; er wandert mit Stufe B nach hinten.

Ebenfalls entfallen gegenüber der Vorfassung: echtzeit_sync.dart (A7) und sync_benachrichtigung.dart (A8). Die einzige verbliebene reine Entscheidungsfunktion des Berichts (berichtFaellig) wohnt in sync_merge.dart — eine eigene Datei für eine Funktion wäre Abstraktion ohne zweiten Aufrufer.

Feature-Details

1. Favoriten-Abgleich (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.

Geltungsbereich: Der Favoriten-Abgleich betrifft ausschließlich die lokale Favorites-Tabelle. Der Stern in der Server-Titel-Ansicht (ServerFavoriteButton, lib/shared/server_favorite_button.dart:42, benutzt in now_playing_screen.dart:279) ist ein anderes System — Navidrome-Starring über navidrome.setFavorite(navidromeId) — und wird von dieser Spec nicht angefasst. Beide erscheinen im Now-Playing-Screen als dasselbe Herz-Symbol; dass sie getrennt bleiben, ist eine Entscheidung, keine Auslassung. PlaylistService.syncFavoritesFromServer() (playlist_service.dart:52-71) ist ein dritter Kanal und heute wirkungslos (db.songExists(navidromeId) gegen lokale UUIDs) — er wird nicht Teil des Abgleichs.

Neu, zwei Mechanismen:

• Sofort-Push beim Antippen: PlaylistService.toggleFavorite schickt online zusätzlich fire-and-forget ein deterministisches set:true/false an den Server (POST /favorites/toggle). 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 additiv).
• Additiver Abgleich beim Sync, neue Phase in synchronisiere():

Die Sync-Phase benutzt nie POST /favorites (Voll-Ersatz). Sie schreibt ausschließlich additiv:

1. GET /favorites → server (Menge von cloudIds).
2. Für jede cloudId in lokal \ server: POST /favorites/toggle mit {"song_id": …, "set": true} (existiert und ist deterministisch: melo_cloud.py:1298-1302 → handle_favorites_toggle:644-688; die Client-Methode ist neu).
3. Für jede cloudId in server \ lokal: lokal Favorit setzen, sofern der Song lokal auflösbar ist.
4. In keiner Richtung wird etwas entfernt.

MeloCloudService.setzeFavoriten (melo_cloud_service.dart:268-280) wird nicht mehr benutzt und entfällt.

Wirkung: Der Datenverlust-Bug aus Ziel 1 ist danach strukturell unmöglich, nicht nur durch eine Regel verhindert — es existiert kein Codepfad mehr, der den Server-Stand ersetzen kann. Deckel: höchstens 200 Pushes je Lauf, der Rest im nächsten Lauf (die Pushes sind idempotent, ein Teilausfall heilt sich beim nächsten Lauf selbst).

GET-Härtung (parseFavoriten):

Ein GET gilt nur als erfolgreich, wenn HTTP 200 und kein error-Schlüssel und favorites als Liste vorhanden ist. Ein fehlender favorites-Schlüssel ist ein Fehler, keine leere Menge; parseFavoriten wirft dann CloudException, genau wie parseListe (melo_cloud_service.dart:99-100) und parseUpload (:111-112) es bereits tun. Hintergrund: der Router verdrahtet für GET /favorites hart 200 (melo_cloud.py:1292-1293), und sechs Handler desselben Servers geben Fehler im 200er-Körper zurück (:418, 491, 545, 766, 1021, 1118).

Bestandsänderung, Teil des Arbeitspakets: test/services/melo_cloud_service_test.dart:98-101 prüft heute ausdrücklich das Gegenteil (expect(parseFavoriten(jsonEncode({'status':'ok'})), isEmpty)) und wird mit umgeschrieben. Das ist kein Regressionsfehler.

Schlägt das GET fehl, wird die Phase übersprungen. Der Unterschied zur Vorfassung: das ist jetzt eine Optimierung (nichts zu tun ohne Server-Stand), keine Sicherheitsregel mehr — ein fälschlich leeres GET würde im schlimmsten Fall die lokalen Favoriten additiv hochpushen, also harmlos und idempotent.

Pull-Richtung, unauflösbare cloudIds:

Server-Favoriten, deren cloudId sich lokal auf keinen Song abbilden lässt (Download fehlgeschlagen, Titel noch nicht geladen), werden übersprungen, nicht gelöscht: Favorites.songId verweist auf Songs.id (database.dart:102-107); ein Favorit ohne Song wäre über watchFavorites() (innerJoin, :371-375) unsichtbar, würde aber über favoriteSongIds() (:534-536) weiter mitgeschleppt und wieder hochgepusht. Der additive Abgleich schreibt sie deshalb weder lokal, noch entfernt er sie serverseitig. Hinweis am selben Ort: favoriteSongIds() liefert auch Favoriten getombsteter Songs — es ist ein schlichtes select(favorites).get() (:534-537) ohne Join auf Songs.deleted, und markMissing (:237-245) setzt nur Songs.deleted, die Favorites-Zeile überlebt. Unter dem additiven Abgleich harmlos, unter jedem Voll-Ersatz nicht.

• Songs ohne cloudId: bleiben lokal-only, tauchen in keiner Richtung im Abgleich auf.

Bekannte Einschränkung (bewusst, dokumentiert):

Der Abgleich ist rein additiv. Ein Ent-Favorisieren wirkt sofort lokal und — online — auch auf dem Server, ist aber nicht geräteübergreifend garantiert: Hält ein zweites Gerät den Favoriten noch, bringt dessen nächster Sync ihn auf allen Geräten zurück. Das gilt für offline und für online entfernte Herzen. Bewusster Tausch, wie in v2: kein Datenverlust ist wichtiger als verlässliche Lösch-Propagation. Falls das in der Praxis stört: Folgeschritt „Basis-Snapshot" (Backlog). Er lässt sich später ohne Umbau ergänzen, weil der Schreibweg dann schon der Delta-Push ist — aus set:true wird zusätzlich set:false.

(Die Vorfassung behauptete an dieser Stelle, Ent-Favorisierungen propagierten über den Sofort-Push und nur offline entfernte Herzen kämen zurück. Das war falsch und ist ersatzlos gestrichen.)

2. Playlist-Sicherung (Stufe 1, einseitig)

Playlist-Sync Stufe 1 = einseitige Sicherung. Die App meldet lokale Playlisten-Änderungen (anlegen / Song hinzufügen / Song entfernen / Reihenfolge) online fire-and-forget an den Server und persistiert die vom Server vergebene cloudId (Drift-Migration Playlists.cloudId TEXT NULL bleibt). Es findet kein Rück-Merge statt: Server-Playlisten werden nur dann lokal angelegt, wenn die lokale Playlisten-Tabelle leer ist (Neuinstallation / Wiederherstellung).

Damit entfallen ersatzlos: Namenszuordnung, Reihenfolge-Schiedsrichter („längerer Stand gewinnt"), Gleichstands-Regel, Tombstone-Semantik und die Abhängigkeit vom fehlenden Rename-Endpunkt. Die Identität stammt immer aus dem eigenen POST /playlists und ist stabil (user_playlists.id ist INTEGER PRIMARY KEY AUTOINCREMENT).

Nicht abgedeckt (dokumentiert): Umbenennungen propagieren nicht. Playlisten-Änderungen auf einem zweiten Gerät erscheinen auf dem ersten nicht. Der beidseitige Playlist-Merge ist eine eigene, spätere Spec.

Vorbedingung (Server-Auftrag, blockierend): melo_cloud.py:505 löscht user_playlist_songs für jede playlist_id ohne user-Bedingung — echte Fremddaten-Löschung. Muss geflickt sein, bevor die App diesen Endpunkt regelmäßig benutzt.

Endpunkte: GET/POST/DELETE /playlists, GET /<id>, POST /<id>/songs, DELETE /<id>/songs/<sid>, PUT /<id>/positions (melo_cloud.py:1251-1284). Einen Rename-Endpunkt gibt es nicht — kein PUT/PATCH auf die Playlist selbst; handle_rename:749 betrifft Songs. (Die Vorfassung behauptete das Gegenteil.)

Songs ohne cloudId in einer Playlist bleiben lokal in der Playlist und werden zum Server einfach nicht mitgemeldet — kein Fehler.

Ebenfalls vertretbar und heute kostenlos (0 Playlisten auf dem Server): Feature 2 ganz herausschneiden. Entscheidung liegt bei Dustin; das Weiterlaufen im Zustand der Vorfassung (vier offene Semantik-Entscheidungen) ist es nicht.

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

• Auswahl-Modus in „Meine Musik“ bekommt die Aktion „Auf den Server laden“. Er existiert (my_music_screen.dart:120 → SortableSongList, lib/shared/sortable_song_list.dart:46-54, :194-196) — zu beachten ist nur das Scoping: SortableSongList wird in fünf Ansichten benutzt, die Aktion würde sonst überall erscheinen.
• Neue Methode SyncService.ladeAusgewaehlteHoch(List<Song> songs): nutzt den bestehenden _ladeHoch-Pfad pro Song, mit Fortschritt über die bestehenden Felder (laeuft/erledigt/gesamt/status).
• 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ß“.
• Abbrechen: Der Auswahl-Upload bekommt SyncService.abbrechen() nach dem Muster von DownloadService (:46, :66-68, :96) — ein Flag, das die Schleife zwischen zwei Songs prüft. SyncService hat heute keinerlei Abbruchmöglichkeit (0 Treffer für abbrech|cancel in 376 Zeilen); ohne das ist ein versehentlich markierter 60-Titel-Upload nur durch App-Kill zu stoppen.
• Zeitstempel: ladeAusgewaehlteHoch schreibt _letzterLauf (:215-217) nicht — es ist kein Sync. Sonst unterdrückt ein manueller Upload 15 Minuten Auto-Sync (sollAutoSync, :120-121) und verschiebt die 24-h-Uhr des Berichts; wer die App täglich zum Hochladen öffnet, sähe den Bericht nie.
• Offline-Modus: Der Schalter (lib/services/offline_mode.dart, settings_screen.dart:218-231) wirkt heute nur auf die Wiedergabe (main.dart:106-110). Entscheidung: der Auswahl-Upload respektiert ihn nicht, weil er eine ausdrückliche Nutzeraktion ist.
• 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):

ladeEinzelnenTitel(song) ruft den bestehenden öffentlichen DownloadService.lade([song]) (download_service.dart:72-111) auf — der bringt Doppel-Lauf-Schutz (:73), Verbindungsprüfung (:77-84) und Fortschritts-Buchführung (:85-104) mit. Nicht _ladeEinen (:113-139) direkt verdrahten.

Gleiche Ablage (App-Speicher, Application-Support/melo_downloads), gleiche Buchführung (Downloads-Tabelle per navidromeId), gleiche Fehlerbehandlung.

• Doppelspeicherung: Vor dem Netz-Download prüft ladeEinzelnenTitel, ob die Datei bereits im Abspiel-Cache liegt — sonst entsteht genau die Doppelspeicherung, die audio_handler.dart:326-331 in der Gegenrichtung ausdrücklich verhindert („doppelter Platz und doppeltes Datenvolumen"). Falls zu teuer: als bekannte Einschränkung dokumentieren, nicht schweigen.
• Kein Platz-Check, keine Schwelle: Die 30er-Rückfrage (download_service.dart:13, :15, :17-21, Aufrufer nur downloads_screen.dart:460 und :496) ist bei einem Einzeltitel per Konstruktion wirkungslos, und einen Check auf freien Speicher gibt es in der ganzen App nicht. Bewusst akzeptiert: der Knopf lädt genau einen Titel.
• Offline-Modus: wird ebenfalls nicht respektiert (ausdrückliche Nutzeraktion, siehe Feature 3).
• UI: Songzeilen in der Server-Album-/Künstler-Ansicht (server_titel_screen.dart) bekommen den Lade-Knopf, den es heute nur pro Album gibt, inklusive Zustand „schon offline“ mit Entfernen-Option (bestehendes DownloadService.entferne). _LadeKnopf ist eine private Klasse in lib/downloads/downloads_screen.dart:419-429, kein wiederverwendbares Widget — als Muster kopieren oder vorher extrahieren.

5. Sync-Bericht („Was ist neu“)

• Rein in-App, keine neue Dependency: 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.
• Erstfall: letzterLauf == null (Neuinstallation, nach Abmelden, nach App-Daten-Löschen) gilt nicht als fällig — sonst begrüßt der Bericht ein frisch installiertes Gerät mit „Willkommen zurück! 325 neue Songs". Achtung: sollAutoSync (sync_service.dart:120-121) behandelt null genau umgekehrt und ist hier kein Vorbild.
• „Erfolgreich" heißt: alle Phasen ohne geschluckten Fehler. Dafür führt synchronisiere() ein Flag, das jede Phase bei einem Fehlschlag löscht; der Bericht-Zeitstempel wird nur bei gesetztem Flag geschrieben. Heute schreibt :215-217 denselben Zeitstempel, egal ob Phasen ausgefallen sind (_meldeLoeschungen:243-252 schluckt Fehler).
• Die Entscheidung „Bericht fällig?“ liegt als reine Funktion (berichtFaellig) in sync_merge.dart und ist ohne Plattform-Kanäle testbar.
• Die In-App-Fortschrittsanzeige in den Einstellungen bleibt wie heute.

Sync-Phasen nach Ausbau (Reihenfolge im Lauf)

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

Der Zeitstempel wird vor dem Listen genommen und nach allen Phasen geschrieben (heute: _letzterLauf = DateTime.now() in :215, nach allen Phasen — der Snapshot-vor-dem-Listen fehlt noch).

Die Playlist-Sicherung (Feature 2) ist keine Sync-Phase: sie läuft als Sofort-Push bei der Änderung, und die Wiederherstellung greift nur bei leerer lokaler Tabelle.

Reihenfolge (Auslieferung)

1. Favoriten-Fix allein (additiver Delta-Push, parseFavoriten, Testanpassung). Wartet auf nichts: kein Server-Auftrag, keine neue Dependency, keine Gradle-Änderung, kein neues UI-Muster. Einzige Stufe mit belegtem Datenverlust-Bezug.
2. Auswahl-Upload + Einzel-Song-Offline (UI, keine neue Dependency).
3. Sync-Bericht (In-App-Dialog, kein Plugin).
4. Playlist-Sicherung Stufe 1 — nach dem Server-Fix melo_cloud.py:505.

Ab hier nicht mehr Inhalt dieser Spec — beides steht unter §Nicht-Ziele bzw. §Spätere Stufen und ist nur der Vollständigkeit halber einsortiert:

5. Notification Stufe B — beginnt mit dem grünen Beweis-Build.
6. SSE — eigene Spec, nach dem song_upload-Event.

Warum genau diese Reihenfolge — Begründung, die mitgebaut werden muss:

• Stufe 1 (A1/A2/A3) berührt den Löschpfad nicht und hängt an keiner offenen Frage. Deshalb kann mit der Umsetzung begonnen werden, ohne dass die Antwort auf die A6-Rückfrage vorliegt. Sie behebt außerdem als einzige einen belegten Datenverlust-Bug — sie zuerst zu liefern ist auch inhaltlich richtig.
• Der Auswahl-Upload (Feature 3) kommt bewusst NACH der Klärung der A6-Rückfrage: Er gibt mehr Titeln eine cloudId und vergrößert damit genau die Angriffsfläche des irreversiblen Löschpfads. Lautet die Antwort „nein, nicht gewollt“, gehört der Server-Auftrag (Datei-Wiederherstellung im Dedup-Zweig) davor.
• Alles, was auf einen fremden Auftrag wartet (Server-Fix :505, song_upload-Event) oder auf einen Build-Umbau (flutter_local_notifications), steht hinten — das betrifft die Stufen 4–6. Innerhalb dieser drei blockiert keine Stufe eine frühere. Für Stufe 2 gilt das ausdrücklich nicht: sie wartet auf die A6-Antwort (Absatz darüber), und Stufe 4 hängt zusätzlich am Server-Fix :505 (§Offene Abhängigkeiten, Zeile 1).

Fehlerfälle — zu bauende Arbeit, keine Zusagen

Fünf in der Vorfassung als „bestehend“ beschriebene Schutzmechanismen existieren nicht und sind Teil dieser Arbeit:

• Phasen-Isolation: synchronisiere() hat heute ein einziges try/catch um alle Phasen (sync_service.dart:188-228). Jede neue Phase bekommt ihr eigenes try/catch mit definiertem Teil-Erfolg.
• „verzögert" gibt es nicht: if (_laeuft) return; (:175) verwirft den Anstoß wortlos. Wer einen Nachlauf will, braucht ein _nachziehen-Flag, das im finally genau einen weiteren Lauf auslöst.
• Der Upload überlebt keinen Timeout: _ladeHoch fängt nur CloudException (:313); der 120-s-Timeout (melo_cloud_service.dart:180) wirft TimeoutException und reißt den ganzen Lauf ab. Timeouts sind wie Einzelfehler zu behandeln.
• Die Drossel sitzt in automatisch() (:166-170), nicht in synchronisiere() (:174-180). Ein Parameter erzwinge wäre deshalb wirkungslos und entfällt ersatzlos (er stammte aus dem gestrichenen SSE-Teil).
• Der Löschweg zum Server wird in den Fehlerfällen nirgends beschrieben — siehe §Risiken, „Irreversibler Löschpfad".

Verhalten im Einzelnen:

• Favoriten-GET scheitert → Phase 4 überspringen, Sync läuft weiter (nichts zu tun ohne Server-Stand; ein blindes additives Pushen wäre harmlos, aber nutzlos).
• Playlist-Endpunkt scheitert → Sofort-Push still verwerfen, nächste Änderung versucht es erneut.
• Auswahl-Upload: Datei >50 MB, Einzel-Upload-Fehler oder Timeout → im Ergebnis vermerken, mit nächstem Song fortfahren; abbrechen() stoppt zwischen zwei Songs.
• Einzel-Song-Offline: wie bestehender Album-Pfad (Fehler pro Titel, kein Abbruch des Rests).
• Sync bereits aktiv → Auswahl-Upload wird abgewiesen (bestehender Schutz, :175).

Risiken

• 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.
• Die Sicherheit der Favoriten liegt nicht mehr in einer Regel, sondern darin, dass kein Voll-Ersatz-Aufruf mehr existiert.
• Der Navidrome-Playlist-Import ist nicht idempotent („🌐“-Duplikate) — Bestandsfehler, von Feature 2 nicht angefasst, aber beim Testen präsent.

Irreversibler Löschpfad (Bestand, nicht von dieser Spec verursacht — Backlog-P0)

markMissing (database.dart:237-245) tombstoned jeden Titel, dessen Datei der Scan nicht findet — auch unbeabsichtigt (SD-Karte nicht eingehängt, Berechtigung entzogen, Dateimanager). planeSync (sync_service.dart:68-76) macht daraus eine Server-Löschung; die Lösch-Bremse (:112-113) greift bei 325 Titeln erst ab 109 — 1 bis 108 Löschungen laufen ungebremst. Der Server löscht registry/<sid> und navidrome/music/<sid> (melo_cloud.py:356-372, :190-202); für die Datei gibt es keinen Grabstein. Erneutes Hochladen repariert es nicht: der überlebende registry.sha256 erzwingt den Dedup-Zweig (:265-267), shutil.move steht nur im Neu-Zweig (:289), os.remove(tmp) verwirft die Bytes (:312), /download antwortet dauerhaft 404 (:1400-1408). Bisher nie ausgelöst (Live-DB: SUM(deleted)=0).

Die zugehörige Rückfrage an Dustin ist noch offen — siehe §OFFENE ENTSCHEIDUNG ganz oben.

Verworfene Alternativen

Verworfen: Drei-Wege-Merge gegen einen persistierten Basis-Snapshot (neu = (lokal ∪ server) − (Basis \ lokal) − (Basis \ server)). Er löst zwar die Lösch-Propagation, führt aber den einzigen neuen Datenverlustpfad der ganzen Planung ein: Liefert GET /favorites fälschlich eine leere Liste, wird Basis \ server = Basis, die Formel kollabiert zu lokal − Basis und löscht den gesamten bestätigten Bestand — lokal und über den Delta-Push auf dem Server und damit auf allen Geräten. Zusätzlich braucht er kontogebundenen Zustand mit Aufräumpflicht beim Abmelden; BakaAuth.abmelden (baka_auth.dart:114-120) räumt heute nichts ab und es gibt kein Token-Refresh. Für drei Nutzer, 0 Favoriten und 0 Playlisten auf dem Server ist der additive Abgleich der bessere Tausch. Der Basis-Snapshot bleibt als Folgeschritt im Backlog.

(Diese Alternative war die Haupt-Empfehlung des Review-Panels. Sie wird mit obiger Begründung abgelehnt — die separate Faktenprüfung hat nachgerechnet, dass ein fälschlich leeres GET, das parseFavoriten heute erzeugt, sie zur geräteübergreifenden Massenlöschung macht.)

Ebenfalls verworfen: der beidseitige Playlist-Merge in dieser Stufe (vier offene Semantik-Entscheidungen, siehe A5) und SSE in dieser Stufe (eigene Vorbedingung nicht erfüllt, siehe §Nicht-Ziele).

Tests

Neu:

• sync_merge.dart: Unit-Tests für die Mengendifferenz beider Richtungen (leer×leer, einseitig, disjunkt, Songs ohne cloudId, unauflösbare Server-cloudId → übersprungen) und für berichtFaellig (null → nicht fällig, <24 h → nicht fällig, >24 h → fällig). Deterministisch, ohne I/O.
• sync_service.dart: neue Phase mit MockClient. Zwei Pflichttests: „200 mit Fehlerkörper → Phase übersprungen, kein Push" und „200 mit favorites: [] → Phase läuft normal durch" (der zweite verhindert, dass der erste durch ein zu scharfes „wirf bei leer" trivial erfüllt wird). Dazu: Auswahl-Upload mit Mischung aus ok/zu groß/schon da, abbrechen() stoppt zwischen zwei Songs, ladeAusgewaehlteHoch schreibt _letzterLauf nicht.
• PlaylistService — der Sofort-Push ist der einzige Online-Kanal der Spec und hatte in der Vorfassung keinen einzigen Testeintrag: toggleFavorite schickt deterministisches set:true/false, nur bei cloudId, Fehler werden geschluckt.
• PlaylistService — Feature 2 (einseitige Sicherung): Sofort-Push je Änderungsart (Playlist anlegen → cloudId wird persistiert; Song hinzufügen/entfernen; Reihenfolge via PUT /<id>/positions), Songs ohne cloudId werden nicht mitgemeldet, Endpunkt-Fehler werden still verworfen (kein lokaler Rollback). Pflichttest für die Kernregel: Server-Playlisten werden nur angelegt, wenn die lokale Playlisten-Tabelle leer ist — Gegentest mit einer lokalen Playlist legt nichts an (kein Rück-Merge).
• Widget-Tests: Auswahl-Modus-Aktion sichtbar + ruft Upload auf (und erscheint nicht in den vier anderen SortableSongList-Ansichten); Einzel-Song-Knopf lädt/entfernt; Bericht-Dialog erscheint nach

  24h-Marke und nicht bei letzterLauf == null.

• Drift-Migration: Test, dass Bestandsdaten die neue Spalte überleben.

Anzupassender Bestand (die Vorfassung nannte ausschließlich neue Tests):

• test/services/melo_cloud_service_test.dart:98-101 — zementiert das []-Verhalten, wird mit der GET-Härtung umgeschrieben.
• test/services/sync_service_test.dart:166-202 („Favoriten werden mit ihren Server-IDs gemeldet") prüft heute genau das Full-Replace-Verhalten, das Ziel 1 beseitigt. Sein MockClient beantwortet jeden Pfad außer /list mit {'status':'ok'} (:196) — unter der neuen Regel liefert GET /favorites dort 200 ohne favorites-Schlüssel und die Phase wird übersprungen. Der Test wird auf den additiven Delta-Push umgeschrieben und bekommt eine explizite /favorites-Antwort. Der Catch-All-Mock darf nicht aufgeweicht werden, um die neue Sicherheitsregel zu umgehen — das ist der schnellste Weg zu Grün und der falsche.
• Dasselbe gilt abgeschwächt für die übrigen sieben Tests derselben Datei.

Offene Abhängigkeiten (geschlossene Liste)

#	Auftrag	Art	Blockiert
1	melo_cloud.py:505 — Owner-Prüfung in handle_playlist_delete	Voraussetzung	Feature 2
2	Datei-Wiederherstellung im Dedup-Zweig von upload()	Voraussetzung, falls die Antwort auf die offene Entscheidung „nein" lautet	Feature 3
3	song_upload-SSE-Event	Voraussetzung für die spätere SSE-Stufe	nichts in dieser Spec
4	Playlist-Rename-Endpunkt (PUT/PATCH)	optional	nichts (Feature 2 braucht ihn nicht mehr)
5	Playlist-Tombstones serverseitig	optional / Backlog	nichts
6	Schema-Divergenz ist_korrupt / uq_user_song (nur in der Live-DB, nicht im CREATE TABLE des Skripts)	optional / Backlog	nichts — trifft nur wiederhergestellte oder Test-Instanzen

Backlog-Notizen

• handle_favorites_get liefert bereits favorited_at (melo_cloud.py:620), lokal existiert Favorites.createdAtMs (database.dart:103) — die Zutat für einen späteren echten Merge ist beidseitig vorhanden, ohne dass der Server geändert werden müsste.
• server_titel_screen._geladen ist ein Einmal-Snapshot (Bestandsfehler) — fällt beim Einbau des Einzel-Song-Knopfs auf.