# Context Brief — Review der Sync-Ausbau-Spec

**Review-Gegenstand:** `/home/dustin/mello-dev/app/docs/superpowers/specs/2026-08-27-sync-ausbau-design.md`

**Review-Modus:** Exhaustive (reines Design-Dokument). ABER: Die Spec macht
viele FAKTISCHE Behauptungen über existierenden Code — solche Behauptungen
bitte präzise gegen den echten Code prüfen (grep/read, read-only).

**Codebase-Zustand:** Branch `fix/p0-vollwertigkeit` in
`/home/dustin/mello-dev/app` (kein Worktree-Sonderfall, Branch aktuell mit
origin). Server-Code: `/home/dustin/scripts/melo_cloud.py` (read-only
ansehen erlaubt, NIE ändern).

## Projekt

Melo: Flutter-Musik-App (Android), schwarz/rot, 5 Tabs. Backend:
Navidrome (Subsonic, read-only) + Melo-Cloud (`melo_cloud.py`,
cloud.baka-net.de, Bearer-JWT via BakaAuth) + yt-Proxy. 602 Tests grün.
Nutzer: Dustin (Admin), Baka, Tinker — kleine private Nutzerbasis,
~330 Songs auf dem Server. Projekt-Prinzip „Ponytail“: minimale, robuste
Lösungen; YAGNI wird ernst genommen.

## Bereits vom Auftraggeber ENTSCHIEDEN (im Brainstorming, mit Begründung)

Reviewer dürfen diese Entscheidungen kritisieren, sollen aber wissen, dass
sie bewusst und informiert getroffen wurden:
1. Cross-Platform (Mac/Win) = eigenes späteres Projekt, NICHT diese Spec.
2. Upload-UX: Auswahl-Modus-Erweiterung; Auto-Upload bleibt zusätzlich.
3. Playlist-Konflikte: Union-Merge (kein LWW, kein read-only).
4. Kein Delta-Protokoll, kein Hintergrund-Sync, kein Chunked-Upload (YAGNI).
5. Favoriten-Merge-Fix ist gesetzt (Datenverlust-Bug).
6. Umfang: Einzel-Song-Offline + Playlist-Sync + Notification/Bericht + SSE.

## Verifizierte Schlüsselfakten aus der Bestandsaufnahme (2026-08-27)

App-Sync (lib/services/sync_service.dart, melo_cloud_service.dart):
- Upload existiert: Multipart POST /upload, 50 MB Limit, 120s Timeout;
  Server-Dedup sha256 + fpcalc-Fingerprint (Jaccard>0.7).
- planeSync() lädt ALLE Songs ohne cloudId hoch; Tombstones beidseitig;
  Lösch-Bremse nur für serverLoeschen (>10 && >1/3).
- _gleicheFavoritenAb() POSTet lokale Favoriten als KOMPLETT-ERSATZ
  (der Datenverlust-Bug); MeloCloudService.favoriten() (GET) existiert,
  wird nie aufgerufen.
- Auto-Sync bei Start/Resume, 15-Min-Drossel (sollAutoSync); Fortschritt
  als ChangeNotifier-Felder, UI nur in settings_screen.dart.
- Kein SSE in der App, kein Playlist-Sync in der App.

Server (melo_cloud.py):
- Endpunkte: list/upload/download/stream(Range)/delete/update/rename/
  playlists(CRUD+songs+positions)/favorites(GET/POST/toggle mit set)/
  history/sync(since)/subscribe(SSE, Heartbeat 30s).
- SSE-Events: song_delete, song_update, song_favorite werden emittiert;
  UPLOAD feuert KEIN Event; playlist_update dokumentiert aber nie emittiert.
- Playlists/Favoriten: harte DELETEs, KEINE Tombstones.
- handle_favorites_sync = Full-Replace. handle_list liefert immer ALLES
  inkl. Grabsteine (kein ETag/Since).
- Uploads landen in /var/lib/melo-cloud/registry/ und werden AKTIV nach
  /home/dustin/navidrome/music gehardlinkt + Navidrome-Scan getriggert.
- Achtung bekanntes Server-Risiko: handle_list selektiert Spalte
  ist_korrupt, die im CREATE-TABLE-Schema fehlt (nur Live-DB hat sie).
- Uploads/Downloads liegen serverseitig komplett im RAM.

Offline (download_service.dart u. a.):
- Alben/Künstler-Download in App-Speicher (Application-Support/
  melo_downloads), Drift-Tabelle Downloads (navidromeId), Fortschritt+
  Abbrechen; Rückfrage ab 30 Titeln. Abspiel-Cache 2 GB LRU getrennt davon.

Melo v2 (Referenz, /home/dustin/mello-dev/referenz/melo-app-code.md):
- Hatte: bidirektionalen Favoriten-Merge (Union) + deterministischen
  set-Push beim Toggle; persistente Sync-Notification (i/n); Sync-Bericht
  nach >24h; Konflikt-Dialog. Bekannte v2-Lektionen: Sync-Zeitstempel =
  Snapshot VOR listSongs (Tombstone-Race MED-1); neue Songs sofort MIT
  cloudId in DB (Doppel-Download MED-2); Dateinamen-Kollisionszähler.

Plattform:
- flutter_local_notifications ist NICHT in pubspec.yaml (wäre neu).
- http-Paket vorhanden (client.send für SSE-Streaming möglich).
- POST_NOTIFICATIONS wird seit kurzem beim App-Start angefragt.
- Drift-DB mit Migrationen vorhanden (database.dart, schemaVersion).

## Regeln für Reviewer

- READ-ONLY: nichts schreiben außer der eigenen State-Datei, keine
  git-Operationen, keine Server-Prozesse anfassen, keine .env lesen.
- Jede Behauptung über existierenden Code mit Datei:Zeile belegen
  (grep/read). Behauptungen ohne Beleg als [UNVERIFIED] taggen.
- Findings-Severity: P0 (blockiert die Spec / Datenverlust), P1 (muss vor
  Implementierung geklärt werden), P2 (sollte), P3 (nice to have).
- Für jedes P0/P1: falsifizierbaren Check nennen (welcher grep/read würde
  es widerlegen?), wenn möglich als verification_command (read-only).