# Plan d'Optimisation des Performances - StripStream

## 🔴 Problèmes Identifiés

### Problème Principal : Pagination côté client au lieu de Komga

**Code actuel problématique :**

```typescript
// library.service.ts - ligne 59
size: "5000"; // Récupère TOUTES les séries d'un coup

// series.service.ts - ligne 69
size: "1000"; // Récupère TOUS les livres d'un coup
```

**Impact :**

- Charge massive en mémoire (stocker 5000 séries)
- Temps de réponse longs (transfert de gros JSON)
- Cache volumineux et inefficace
- Pagination manuelle côté serveur Node.js

### Autres Problèmes

1. **TRIPLE cache conflictuel**

   - **Service Worker** : Cache les données API dans `DATA_CACHE` avec SWR
   - **ServerCacheService** : Cache côté serveur avec SWR
   - **Headers HTTP** : `Cache-Control` sur les routes API
   - Comportements imprévisibles, données désynchronisées

2. **Clés de cache trop larges**

   - `library-{id}-all-series` → stocke TOUT
   - Pas de clé par page/filtres

3. **Préférences rechargées à chaque requête**

   - `PreferencesService.getPreferences()` fait une query DB à chaque fois
   - Pas de mise en cache des préférences

4. **ISR mal configuré**
   - `export const revalidate = 60` sur routes dynamiques
   - Conflit avec le cache serveur

---

## ✅ Plan de Développement

### Phase 1 : Pagination Native Komga (PRIORITÉ HAUTE)

- [x] **1.1 Refactorer `LibraryService.getLibrarySeries()`**

  - Utiliser directement la pagination Komga
  - Endpoint: `POST /api/v1/series/list?page={page}&size={size}`
  - Supprimer `getAllLibrarySeries()` et le slice manuel
  - Passer les filtres (unread, search) directement à Komga

- [x] **1.2 Refactorer `SeriesService.getSeriesBooks()`**

  - Utiliser directement la pagination Komga
  - Endpoint: `POST /api/v1/books/list?page={page}&size={size}`
  - Supprimer `getAllSeriesBooks()` et le slice manuel (gardée pour book.service.ts)

- [x] **1.3 Adapter les clés de cache**

  - Clé incluant page + size + filtres
  - Format: `library-{id}-series-p{page}-s{size}-u{unread}-q{search}` ✅
  - Format: `series-{id}-books-p{page}-s{size}-u{unread}` ✅

- [x] **1.4 Mettre à jour les routes API**
  - `/api/komga/libraries/[libraryId]/series` ✅ (utilise déjà `LibraryService.getLibrarySeries()` refactoré)
  - `/api/komga/series/[seriesId]/books` ✅ (utilise déjà `SeriesService.getSeriesBooks()` refactoré)

### Phase 2 : Simplification du Cache (Triple → Simple)

**Objectif : Passer de 3 couches de cache à 1 seule (ServerCacheService)**

- [x] **2.1 Désactiver le cache SW pour les données API**

  - Modifier `sw.js` : retirer le cache des routes `/api/komga/*` (sauf images)
  - Garder uniquement le cache SW pour : images, static, navigation
  - Le cache serveur suffit pour les données

- [x] **2.2 Supprimer les headers HTTP Cache-Control**

  - Retirer `Cache-Control` des NextResponse dans les routes API
  - Évite les conflits avec le cache serveur
  - Note: Conservé pour les images de pages de livres (max-age=31536000)

- [x] **2.3 Supprimer `revalidate` des routes dynamiques**

  - Routes API = dynamiques, pas besoin d'ISR
  - Le cache serveur suffit

- [x] **2.4 Optimiser les TTL ServerCacheService**
  - Réduire TTL des listes paginées (2 min) ✅
  - Garder TTL court pour les données avec progression (2 min) ✅
  - Garder TTL long pour les images (7 jours) ✅

**Résultat final :**

| Type de donnée   | Cache utilisé      | Stratégie     |
| ---------------- | ------------------ | ------------- |
| Images           | SW (IMAGES_CACHE)  | Cache-First   |
| Static (\_next/) | SW (STATIC_CACHE)  | Cache-First   |
| Données API      | ServerCacheService | SWR           |
| Navigation       | SW                 | Network-First |

### Phase 3 : Optimisation des Préférences

- [ ] **3.1 Cacher les préférences utilisateur**

  - Créer `PreferencesService.getCachedPreferences()`
  - TTL court (1 minute)
  - Invalidation manuelle lors des modifications

- [ ] **3.2 Réduire les appels DB**
  - Grouper les appels de config Komga + préférences
  - Request-level caching (par requête HTTP)

### Phase 4 : Optimisation du Home

- [ ] **4.1 Paralléliser intelligemment les appels Komga**

  - Les 5 appels sont déjà en parallèle ✅
  - Vérifier que le circuit breaker ne bloque pas

- [ ] **4.2 Réduire la taille des données Home**
  - Utiliser des projections (ne récupérer que les champs nécessaires)
  - Limiter à 10 items par section (déjà fait ✅)

### Phase 5 : Nettoyage et Simplification

- [ ] **5.1 Supprimer le code mort**

  - `getAllLibrarySeries()` (après phase 1)
  - `getAllSeriesBooks()` (après phase 1)

- [ ] **5.2 Documenter la nouvelle architecture**

  - Mettre à jour `docs/caching.md`
  - Documenter les nouvelles clés de cache

- [ ] **5.3 Ajouter des métriques**
  - Temps de réponse des requêtes Komga
  - Hit/Miss ratio du cache
  - Taille des payloads

---

## 📝 Implémentation Détaillée

### Phase 1.1 : Nouveau `LibraryService.getLibrarySeries()`

```typescript
static async getLibrarySeries(
  libraryId: string,
  page: number = 0,
  size: number = 20,
  unreadOnly: boolean = false,
  search?: string
): Promise<LibraryResponse<Series>> {
  const headers = { "Content-Type": "application/json" };

  // Construction du body de recherche pour Komga
  const condition: Record<string, any> = {
    libraryId: { operator: "is", value: libraryId },
  };

  // Filtre unread natif Komga
  if (unreadOnly) {
    condition.readStatus = { operator: "is", value: "IN_PROGRESS" };
    // OU utiliser: complete: { operator: "is", value: false }
  }

  const searchBody = { condition };

  // Clé de cache incluant tous les paramètres
  const cacheKey = `library-${libraryId}-series-p${page}-s${size}-u${unreadOnly}-q${search || ''}`;

  const response = await this.fetchWithCache<LibraryResponse<Series>>(
    cacheKey,
    async () => {
      const params: Record<string, string> = {
        page: String(page),
        size: String(size),
        sort: "metadata.titleSort,asc",
      };

      // Filtre de recherche
      if (search) {
        params.search = search;
      }

      return this.fetchFromApi<LibraryResponse<Series>>(
        { path: "series/list", params },
        headers,
        { method: "POST", body: JSON.stringify(searchBody) }
      );
    },
    "SERIES"
  );

  // Filtrer les séries supprimées côté client (léger)
  response.content = response.content.filter((series) => !series.deleted);

  return response;
}
```

### Phase 1.2 : Nouveau `SeriesService.getSeriesBooks()`

```typescript
static async getSeriesBooks(
  seriesId: string,
  page: number = 0,
  size: number = 24,
  unreadOnly: boolean = false
): Promise<LibraryResponse<KomgaBook>> {
  const headers = { "Content-Type": "application/json" };

  const condition: Record<string, any> = {
    seriesId: { operator: "is", value: seriesId },
  };

  if (unreadOnly) {
    condition.readStatus = { operator: "isNot", value: "READ" };
  }

  const searchBody = { condition };

  const cacheKey = `series-${seriesId}-books-p${page}-s${size}-u${unreadOnly}`;

  const response = await this.fetchWithCache<LibraryResponse<KomgaBook>>(
    cacheKey,
    async () =>
      this.fetchFromApi<LibraryResponse<KomgaBook>>(
        {
          path: "books/list",
          params: {
            page: String(page),
            size: String(size),
            sort: "number,asc",
          },
        },
        headers,
        { method: "POST", body: JSON.stringify(searchBody) }
      ),
    "BOOKS"
  );

  // Filtrer les livres supprimés côté client (léger)
  response.content = response.content.filter((book) => !book.deleted);

  return response;
}
```

### Phase 2.1 : Modification du Service Worker

```javascript
// sw.js - SUPPRIMER cette section
// Route 3: API data → Stale-While-Revalidate (if cacheable)
// if (isApiDataRequest(url.href) && shouldCacheApiData(url.href)) {
//   event.respondWith(staleWhileRevalidateStrategy(request, DATA_CACHE));
//   return;
// }

// Garder uniquement :
// - Route 1: Images → Cache-First
// - Route 2: RSC payloads → Stale-While-Revalidate (pour navigation)
// - Route 4: Static → Cache-First
// - Route 5: Navigation → Network-First
```

**Pourquoi supprimer le cache SW des données API ?**

- Le ServerCacheService fait déjà du SWR côté serveur
- Pas de bénéfice à cacher 2 fois
- Simplifie l'invalidation (un seul endroit)
- Les données restent accessibles en mode online via ServerCache

### Phase 2.2 : Routes API simplifiées

```typescript
// libraries/[libraryId]/series/route.ts
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ libraryId: string }> }
) {
  const libraryId = (await params).libraryId;
  const searchParams = request.nextUrl.searchParams;

  const page = parseInt(searchParams.get("page") || "0");
  const size = parseInt(searchParams.get("size") || "20");
  const unreadOnly = searchParams.get("unread") === "true";
  const search = searchParams.get("search") || undefined;

  const [series, library] = await Promise.all([
    LibraryService.getLibrarySeries(libraryId, page, size, unreadOnly, search),
    LibraryService.getLibrary(libraryId),
  ]);

  // Plus de headers Cache-Control !
  return NextResponse.json({ series, library });
}

// Supprimer: export const revalidate = 60;
```

---

## 📊 Gains Attendus

| Métrique                  | Avant        | Après (estimé) |
| ------------------------- | ------------ | -------------- |
| Payload initial Library   | ~500KB - 5MB | ~10-50KB       |
| Temps 1ère page Library   | 2-10s        | 200-500ms      |
| Mémoire cache par library | ~5MB         | ~50KB/page     |
| Requêtes Komga par page   | 1 grosse     | 1 petite       |

---

## ⚠️ Impact sur le Mode Offline

**Avant (triple cache) :**

- Données API cachées par le SW → navigation offline possible

**Après (cache serveur uniquement) :**

- Données API non cachées côté client
- Mode offline limité aux images déjà vues
- Page offline.html affichée si pas de connexion

**Alternative si offline critique :**

- Option 1 : Garder le cache SW uniquement pour les pages "Home" et "Library" visitées
- Option 2 : Utiliser IndexedDB pour un vrai mode offline (plus complexe)
- Option 3 : Accepter la limitation (majoritaire pour un reader de comics)

---

## 🔧 Tests à Effectuer

- [ ] Test pagination avec grande bibliothèque (>1000 séries)
- [ ] Test filtres (unread, search) avec pagination
- [ ] Test changement de page rapide (pas de race conditions)
- [ ] Test invalidation cache (refresh)
- [ ] Test mode offline → vérifier que offline.html s'affiche
- [ ] Test images offline → doivent rester accessibles

---

## 📅 Ordre de Priorité

1. **Urgent** : Phase 1 (pagination native) - Impact maximal
2. **Important** : Phase 2 (simplification cache) - Évite les bugs
3. **Moyen** : Phase 3 (préférences) - Optimisation secondaire
4. **Faible** : Phase 4-5 (nettoyage) - Polish

---

## Notes Techniques

### API Komga - Pagination

L'API Komga supporte nativement :

- `page` : Index de page (0-based)
- `size` : Nombre d'éléments par page
- `sort` : Tri (ex: `metadata.titleSort,asc`)

Endpoint POST `/api/v1/series/list` accepte un body avec `condition` pour filtrer.

### Filtres Komga disponibles

```json
{
  "condition": {
    "libraryId": { "operator": "is", "value": "xxx" },
    "readStatus": { "operator": "is", "value": "IN_PROGRESS" },
    "complete": { "operator": "is", "value": false }
  }
}
```

### Réponse paginée Komga

```json
{
  "content": [...],
  "pageable": { "pageNumber": 0, "pageSize": 20 },
  "totalElements": 150,
  "totalPages": 8,
  "first": true,
  "last": false
}
```