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

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

Status: Freigegeben, umsetzungsbereit (2026-08-27). Nachgeschärft nach agent-review-panel (Urteil Phase 14: Score 6/10, Verdikt „Spec nachschärfen dann freigeben"), alle 17 Aktionspunkte A1–A17 eingearbeitet, Gegenlesen durch einen frischen Prüfer bestanden (Bedingung des Richters erfüllt). Die einzige offene Frage (A6, Löschpfad) ist beantwortet und serverseitig behoben — siehe §ERLEDIGT. Keine Stufe ist blockiert. Implementierungsplan: docs/superpowers/plans/2026-08-27-sync-ausbau.md (13 Tasks).

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).

ERLEDIGT — Löschpfad ist gefixt (2026-08-27)

Die Rückfrage an Dustin („Ist der irreversible Löschpfad gewollt?") ist beantwortet: nein. Hermes hat den Fix am selben Tag in melo_cloud.py eingebaut und den Dienst neu gestartet.

Was sich geändert hat: Im Dedup-Zweig von upload() prüft der Server jetzt registry_pfad(sid) is None und stellt in diesem Fall die Datei aus den hochgeladenen Bytes wieder her (shutil.move nach REG plus UPDATE registry SET path), statt sie über os.remove(tmp) zu verwerfen. Der bestehende verknuepfe_navidrome-Aufruf hängt sie danach automatisch zurück in die Navidrome-Bibliothek.

End-to-End verifiziert (2026-08-27, eigene Testdatei, Fake-Nutzer, Testdaten danach restlos entfernt — Registry vor und nach dem Test bei 325 Titeln): Upload → beide Kopien da, Download bitgenau · Löschung → beide Dateien weg, Download 404 (Bug reproduziert) · erneuter Upload → beide Dateien zurück, Download wieder bitgenau identisch.

Folge für diese Spec: keine Stufe ist mehr blockiert. Der ursprüngliche Grund, Feature 3 (Auswahl-Upload) hinter die Klärung zu stellen — es gibt mehr Titeln eine cloudId und vergrößert damit die Angriffsfläche —, ist entfallen: Ein versehentlicher Löschvorgang ist jetzt durch erneutes Hochladen reparabel. Die Reihenfolge in §Reihenfolge bleibt trotzdem so bestehen, weil sie auch aus anderen Gründen sinnvoll ist (Stufe 1 behebt den einzigen belegten Bug und hängt an nichts).

Nebenbefund aus dem Test, nicht blockierend: _link_user() wird nur im Dedup-Zweig aufgerufen (der Neu-Zweig kehrt vorher zurück) und legt einen dritten Hardlink unter users/<user>/<sid>.mp3 an, den _entferne_datei_wenn_verwaist() beim Löschen nicht mit abräumt. Bisher folgenlos (das Verzeichnis war leer, weil im Normalbetrieb fast alles über den Neu-Zweig läuft), aber jeder künftige Dedup-Upload hinterlässt einen verwaisten Hardlink. Server-Hygiene für Hermes, kein Datenverlust.

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. Sie behebt außerdem als einzige einen belegten Datenverlust-Bug — sie zuerst zu liefern ist auch inhaltlich richtig.
• Der Auswahl-Upload (Feature 3) stand ursprünglich hinter der A6-Klärung, weil er mehr Titeln eine cloudId gibt und damit die Angriffsfläche des Löschpfads vergrößert. Dieser Grund ist seit dem 2026-08-27 entfallen (Löschpfad serverseitig entschärft, siehe §ERLEDIGT). Die Stufe bleibt an ihrer Position, weil Stufe 1 den einzigen belegten Bug behebt und deshalb vorne gehört — nicht mehr, weil Stufe 2 blockiert wäre.
• Alles, was auf einen fremden Auftrag wartet (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.

Stand 2026-08-27: keine Stufe dieser Spec ist mehr blockiert. Die einzige offene Fremdabhängigkeit (song_upload-Event) betrifft ausschließlich die spätere SSE-Stufe, die nicht Teil dieser Spec ist.

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.

Löschpfad (war Backlog-P0 — am 2026-08-27 serverseitig entschärft)

Der folgende Abschnitt beschreibt den Stand VOR dem Fix. Die Kette selbst besteht unverändert — eine verschwundene lokale Datei führt weiterhin zur Server-Löschung. Was sich geändert hat: Sie ist nicht mehr irreversibel. Erneutes Hochladen derselben Datei stellt sie jetzt in Registry und Navidrome-Bibliothek wieder her (siehe §ERLEDIGT ganz oben). Der letzte Satz des Kastens („Erneutes Hochladen repariert es nicht") gilt daher nicht mehr.

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 beantwortet und behoben — siehe §ERLEDIGT ganz oben. Was bleibt: Die App tombstoned weiterhin großzügig (nicht eingehängte SD-Karte genügt), und die Lösch-Bremse greift weiterhin erst ab 109 von 325 Titeln. Beides ist App-Seite, bewusst unangetastet und kein Blocker — der Schaden ist jetzt reparabel. Ob die App zusätzlich vorsichtiger tombstonen soll, bleibt eine offene Backlog-Frage.

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()	✅ ERLEDIGT 2026-08-27 (Hermes; end-to-end verifiziert)	nichts mehr
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.
• Server-Hygiene (2026-08-27 beim Löschpfad-Test gefunden): _link_user() wird nur im Dedup-Zweig von upload() aufgerufen (der Neu-Zweig kehrt vorher zurück) und legt einen dritten Hardlink unter users/<user>/<sid>.mp3 an, den _entferne_datei_wenn_verwaist() beim Löschen nicht mit abräumt. Bisher folgenlos — das Verzeichnis war leer, weil im Normalbetrieb fast alles über den Neu-Zweig läuft. Seit dem Wiederherstellungs-Fix hinterlässt aber jeder Dedup-Upload einen verwaisten Hardlink. Auftrag an Hermes, kein Datenverlust, eilt nicht.
• App-Seite, bewusst offen: markMissing tombstoned großzügig (eine nicht eingehängte SD-Karte genügt) und die Lösch-Bremse greift erst ab 109 von 325 Titeln. Seit dem Server-Fix ist der Schaden reparabel, also kein Blocker — ob die App trotzdem vorsichtiger tombstonen soll, ist eine eigene Entscheidung.