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)

```swift
@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

```swift
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`