wordeck-native/docs/OFFLINE_SYNC.md

Offline-Sync — wordeck-native

Status: Konzept-Draft (2026-05-18). Implementierung als Phase ζ-1 / ζ-2 in PLAN.md geplant, noch nicht begonnen.

Ziel

Alle Decks des Users — eigene + abonnierte Marketplace-Forks — sollen automatisch beim Login / App-Foreground gecacht werden, so dass der komplette „Heute fällige Karten lernen"-Pfad ohne Netz funktioniert. Grades laufen wie heute über die GradeQueue und drainen beim Reconnect.

Warum jetzt einfach

Mit dem Wordeck-Text-Only-Rebrand (2026-05-17) sind Bilder und Audio aus dem Schema raus. Eine Karte ist jetzt nur noch {type, fields: [String:String], deck_id, …} — pure Text. Damit ist die komplette Offline-Payload JSON-only:

Bestandteil	Größe pro Eintrag	Bei 10 000 Karten
Card-Record (text-only)	≈ 300 B JSON	≈ 3 MB
Review-Snapshot (FSRS-State)	≈ 150 B	≈ 1,5 MB
Distractor-Pool (nur MC, ≈ 10/Karte)	≈ 500 B	≈ 0,5 MB (pro MC-Karte)

Selbst Power-User mit 50 Decks und 5 000 Karten landen unter 5 MB Total-Footprint. SwiftData verkraftet das mit Links.

Server-Invariante bleibt

FSRS rechnet weiterhin nur am Server. Lokales FSRS bleibt verboten (CLAUDE.md §1). Der Offline-Modus ist ein Snapshot- Modell: der Client lernt das, was der Server beim letzten Sync als „due" markiert hat, schickt Grades hinterher, holt nach Sync einen frischen Snapshot. Mehr ist nicht erlaubt.

Architektur

┌────────────────────────────────────────────────────────────┐
│                    DeckListStore.refresh()                  │
│                                                             │
│  GET /decks ──┐                                             │
│               ├── TaskGroup ── per Deck ──┬── listCards()  │
│               │                            ├── dueReviews()│
│               │                            └── distractors │
│               │                                            │
│               ▼                                            │
│        SwiftData-Persistenz                                │
│        ┌─────────────┐ ┌────────────┐ ┌──────────────┐    │
│        │ CachedDeck  │ │ CachedCard │ │ CachedDue    │    │
│        │             │ │            │ │   Review     │    │
│        │ (heute)     │ │ (neu)      │ │ (neu)        │    │
│        └─────────────┘ └────────────┘ └──────────────┘    │
│                                                             │
└────────────────────────────────────────────────────────────┘
                              │
                              ▼
       ┌────────────────────────────────────────────┐
       │           StudySession.start()              │
       │                                             │
       │   try:  api.dueReviews(deckId)              │
       │   fall: CachedDueReview (deckId)            │
       │                                             │
       │   grade → GradeQueue (PendingGrade)         │
       │                                             │
       └────────────────────────────────────────────┘

Daten-Modelle (neu)

@Model
final class CachedCard {
    @Attribute(.unique) var id: String        // card_id
    var deckId: String
    var userId: String
    var typeRaw: String                       // CardType.rawValue
    var fields: [String: String]              // pures JSON-Field-Bag
    var contentHash: String?
    var createdAt: Date
    var updatedAt: Date
    var lastFetchedAt: Date

    // Multiple-Choice-Pool für Offline-Rendering.
    // Leer für non-MC-Karten.
    var distractorPool: [String] = []
}

@Model
final class CachedDueReview {
    @Attribute(.unique) var compoundId: String  // "\(cardId)-\(subIndex)"
    var cardId: String
    var subIndex: Int
    var deckId: String                          // Index für StudySession-Lookup
    var due: Date                               // Server-berechnet
    var stability: Double
    var difficulty: Double
    var stateRaw: String                        // ReviewState
    var lastReview: Date?
    var snapshottedAt: Date                     // wann gepullt
}

API-Endpoints (vorhanden, kein Server-Change nötig)

Endpoint	Verwendung	Limit
GET /api/v1/cards?deck_id=X	komplette Card-Liste pro Deck	kein Limit
GET /api/v1/reviews/due?deck_id=X&limit=500	due-Snapshot	500 ⚠
GET /api/v1/decks/:deckId/distractors?card_id=Y&field=back&count=10	MC-Pool	10

Sync-Algorithmus (DeckListStore.refresh() erweitert)

1. GET /decks → remoteDecks
2. Diff Cache ↔ remoteDecks, gelöschte Decks aus Cache entfernen
3. Für jedes Deck parallel (TaskGroup):
   a. listCards(deckId) → in CachedCard upserten
   b. dueReviews(deckId, limit: 500) → CachedDueReview ersetzen
      (nicht mergen — Snapshot überschreibt komplett, weil due-Zeiten
      sich serverseitig ändern können)
   c. Für jede MC-Karte: distractors(deckId, cardId, count: 10) →
      CachedCard.distractorPool
4. WidgetSnapshot updaten (heute schon, bleibt)

StudySession-Anpassung

func start() async {
    phase = .loading
    do {
        queue = try await api.dueReviews(deckId: deckId, limit: 500)
        // ... wie heute
    } catch {
        // Netz-Fehler → Cache befragen
        queue = loadFromCache(deckId: deckId)
        if queue.isEmpty {
            phase = .failed("Kein Netz und keine gecachten Karten.")
        } else {
            Log.study.notice("Offline-Mode: \(queue.count) cached due reviews")
            phase = .studying
            isOfflineSession = true
        }
    }
}

Beim Grade-Submit ändert sich nichts: GradeQueue.submit() persistiert eh erst lokal und drained später. Das funktioniert heute schon offline.

Trigger

Wann	Was
App-Foreground / Login	DeckListStore.refresh() (heute) → erweitert auf Card+Review+Distractor-Sync
Pull-to-Refresh in DeckListView	dasselbe
Nach subscribe(slug:) im Marketplace	direkt refresh() aufrufen, damit das frisch abonnierte Deck sofort komplett gecacht ist
BGAppRefreshTask (alle ~12 h, optional, β-7-Polish)	Drain Grade-Queue + Refresh; nur wenn wifi_only=true erlaubt oder User hat Mobile-Sync aktiv

Settings (in SettingsView)

• Auto-Sync (Default: an) — schaltet Card/Review-Prefetch ein/aus
• Background-Refresh (Default: aus) — BGAppRefreshTask
• Cache-Footprint anzeigen — „17 Decks, 1 234 Karten, 4,2 MB"
• Cache leeren — Wipe aller CachedCard + CachedDueReview, CachedDeck bleibt (sonst Deck-Liste leer)

Phasen

Phase	Inhalt	Aufwand
ζ-1	CachedCard + Sync in DeckListStore, StudySession-Cache-Fallback	1 Tag
ζ-2	CachedDueReview + Distractor-Pool für MC-Karten	0,5 Tag
ζ-3	SettingsView-Footprint + Cache-Clear	0,5 Tag
ζ-4 (optional)	BGAppRefreshTask, Wi-Fi-Only-Toggle	0,5 Tag

Endurance-Pflicht (siehe PLAN.md): 200+ Karten offline lernen, Flugmodus, alle Grades landen nach Reconnect am Server, Cross- Check mit Web-Review-State.

Offene Punkte

• 🛑 dueReviews(limit: 500) ist hardcoded — Decks > 500 Karten haben einen stillen Cap. Wenn ein Marketplace-Deck mehr als 500 fällige Karten hat (passiert bei frischen Abos), bekommt der Client offline nur die ersten 500. Optionen:
  • (a) Pagination einbauen (offset=…) und mehrere Calls chainen — billig.
  • (b) Server-Endpoint /api/v1/reviews/due-all?deck_id=X der paginiert in einer Response liefert — sauberer, braucht Backend-PR.
  • (c) Aktzeptieren, Banner „Sync unvollständig — weitere Karten erst nach Online-Refresh". Vorschlag: (a) zunächst, Schwelle im Snapshot loggen.
• 🛑 Distractor-Pool drifted, wenn der User Karten löscht. Ein Pool von 10 Distractors zur Sync-Zeit kann nach Lösch- Aktionen Treffer in der Liste haben, die offline nicht mehr existieren. Akzeptabel, weil MC-Distractors ohnehin „Fülltext" sind — Reveal-Korrekt-Highlight kommt vom answer-Feld der Karte, nicht aus dem Pool.
• 🛑 „Mehr Karten als der Snapshot enthält" — wenn User offline alle 100 fälligen Karten durchgelernt hat und weiter klickt, gibt es keinen lokalen Weg, „nächste fällige Karte" zu bestimmen. UX-Honest: am Ende der Session Banner zeigen („Weitere Karten erst nach Verbindung verfügbar"), Server- authoritative-FSRS bleibt damit intakt.
• 🛑 SwiftData-Migration. Schema-Update von Build 11 → ζ-1 legt zwei neue @Model-Klassen an. Bei In-Place-Upgrade von TestFlight-Buildern muss der ModelContainer mit MigrationPlan versorgt werden — sonst Crash beim ersten Start nach Update. Wir haben das vorher noch nicht gebraucht; für ζ-1 Pflicht-Aufgabe vor Submit.
• 🛑 Cache-Invalidierung bei Cross-Device-Edits. User editiert Karte auf Web → Native zeigt offline noch alte Version, bis der nächste Refresh läuft. Heute akzeptabel — updatedAt-Vergleich beim Sync wirft die alte Version raus. Wenn das in der Praxis weh tut, kann später ein Web-Push-Hook auf card.updated einen Targeted-Refresh triggern (nicht ζ-Scope).
• 🛑 Logout = Cache-Wipe. Bei Sign-out alle CachedCard + CachedDueReview löschen. Heute macht auth.signOut() das nicht. Muss in ζ-1 mit rein.

Was nicht in ζ kommt

• Lokales FSRS-Berechnen — verboten per CLAUDE.md §1.
• Offline-Card-Create — Editor bleibt online-only. Drafting ohne Netz wäre nett, hat aber Konflikt-Auflösung als Folge- Problem. Aufgeschoben bis nach v1.
• Media-Prefetch — gegenstandslos seit Wordeck-Rebrand (text-only).

Cross-Refs

• CLAUDE.md — Architektur-Invarianten (§1 FSRS, §2 Offline-Read)
• PLAN.md — Phasen-Stand
• ../mana/docs/playbooks/WORDECK_REBRAND.md — Text-Only-Cut
• ../mana/docs/playbooks/CARDS_NATIVE_GREENFIELD.md — Greenfield-SOT
• ../wordeck/apps/api/src/routes/cards.ts — GET /cards?deck_id
• ../wordeck/apps/api/src/routes/reviews.ts — GET /reviews/due
• ../wordeck/apps/api/src/routes/decks.ts — /distractors