refactor: remove caching-related API endpoints and configurations, update preferences structure, and clean up unused services

2026-01-03 18:55:12 +01:00
parent acd26ea427
commit 512e9a480f
49 changed files with 244 additions and 4073 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -27,22 +27,6 @@
 - **Body** : `{ url: string, username: string, password: string }`
 - **Réponse** : `{ message: string, config: Config }`

-### GET /api/komga/ttl-config
-
- **Description** : Récupération de la configuration TTL du cache
- **Réponse** : `{ defaultTTL: number, homeTTL: number, ... }`
-
-### POST /api/komga/ttl-config
-
- **Description** : Sauvegarde de la configuration TTL
- **Body** : `{ defaultTTL: number, homeTTL: number, ... }`
- **Réponse** : `{ message: string, config: TTLConfig }`
-
-### GET /api/komga/cache/mode
-
- **Description** : Récupération du mode de cache actuel
- **Réponse** : `{ mode: string }`
-
 ## 📚 Bibliothèques

 ### GET /api/komga/libraries
@@ -123,13 +107,13 @@
 ### GET /api/preferences

 - **Description** : Récupération des préférences utilisateur
- **Réponse** : `{ showThumbnails: boolean, cacheMode: "memory" | "file", showOnlyUnread: boolean, debug: boolean }`
+- **Réponse** : `{ showThumbnails: boolean, showOnlyUnread: boolean, displayMode: object, background: object, readerPrefetchCount: number }`

 ### PUT /api/preferences

 - **Description** : Mise à jour des préférences utilisateur
- **Body** : `{ showThumbnails?: boolean, cacheMode?: "memory" | "file", showOnlyUnread?: boolean, debug?: boolean }`
- **Réponse** : `{ showThumbnails: boolean, cacheMode: "memory" | "file", showOnlyUnread: boolean, debug: boolean }`
+- **Body** : `{ showThumbnails?: boolean, showOnlyUnread?: boolean, displayMode?: object, background?: object, readerPrefetchCount?: number }`
+- **Réponse** : `{ showThumbnails: boolean, showOnlyUnread: boolean, displayMode: object, background: object, readerPrefetchCount: number }`

 ## 🧪 Test

--- a/docs/caching.md
+++ b/docs/caching.md
@@ -1,549 +0,0 @@
-# Système de Caching
-
-Ce document décrit l'architecture et les stratégies de caching de StripStream.
-
-## Vue d'ensemble
-
-Le système de caching est organisé en **3 couches indépendantes** avec des responsabilités clairement définies :
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        NAVIGATEUR                            │
-│  ┌────────────────────────────────────────────────────────┐ │
-│  │  Service Worker (Cache API)                            │ │
-│  │  → Offline support                                     │ │
-│  │  → Images (covers + pages)                             │ │
-│  └────────────────────────────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│                      SERVEUR NEXT.JS                         │
-│  ┌────────────────────────────────────────────────────────┐ │
-│  │  ServerCacheService                                    │ │
-│  │  → Données API Komga                                   │ │
-│  │  → Stale-while-revalidate                              │ │
-│  │  → Mode fichier ou mémoire                             │ │
-│  └────────────────────────────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│                      SERVEUR KOMGA                           │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Couche 1 : Service Worker (Client)
-
-### Fichier
-
-`public/sw.js`
-
-### Responsabilité
-
- Support offline de l'application
- Cache persistant des images (couvertures et pages de livres)
- Cache des ressources statiques Next.js
-
-### Stratégies
-
-#### Images : Cache-First
-
-```javascript
-// Pour toutes les images (covers + pages)
-const isImageResource = (url) => {
-  return (
-    (url.includes("/api/v1/books/") &&
-      (url.includes("/pages") || url.includes("/thumbnail") || url.includes("/cover"))) ||
-    (url.includes("/api/komga/images/") &&
-      (url.includes("/series/") || url.includes("/books/")) &&
-      url.includes("/thumbnail"))
-  );
-};
-```
-
-**Comportement** :
-
-1. Vérifier si l'image est dans le cache
-2. Si oui → retourner depuis le cache
-3. Si non → fetch depuis le réseau
-4. Si succès → mettre en cache + retourner
-5. Si échec → retourner 404
-
-**Avantages** :
-
- Performance maximale (lecture instantanée depuis le cache)
- Fonctionne offline une fois les images chargées
- Économise la bande passante
-
-#### Navigation et ressources statiques : Network-First
-
-```javascript
-// Pour les pages et ressources _next/static
-event.respondWith(
-  fetch(request)
-    .then((response) => {
-      // Mise en cache si succès
-      if (response.ok && (isNextStaticResource || isNavigation)) {
-        cache.put(request, response.clone());
-      }
-      return response;
-    })
-    .catch(async () => {
-      // Fallback sur le cache si offline
-      const cachedResponse = await cache.match(request);
-      if (cachedResponse) return cachedResponse;
-
-      // Page offline si navigation
-      if (request.mode === "navigate") {
-        return cache.match("/offline.html");
-      }
-    })
-);
-```
-
-**Avantages** :
-
- Toujours la dernière version quand online
- Fallback offline si nécessaire
- Navigation fluide même sans connexion
-
-### Caches
-
-| Cache                   | Usage                        | Stratégie     | Taille   |
-| ----------------------- | ---------------------------- | ------------- | -------- |
-| `stripstream-cache-v1`  | Ressources statiques + pages | Network-First | ~5 MB    |
-| `stripstream-images-v1` | Images (covers + pages)      | Cache-First   | Illimité |
-
-### Nettoyage
-
- Automatique lors de l'activation du Service Worker
- Suppression des anciennes versions de cache
- Pas d'expiration (contrôlé par l'utilisateur via les paramètres du navigateur)
-
-## Couche 2 : ServerCacheService (Serveur)
-
-### Fichier
-
-`src/lib/services/server-cache.service.ts`
-
-### Responsabilité
-
- Cache des réponses API Komga côté serveur
- Optimisation des temps de réponse
- Réduction de la charge sur Komga
-
-### Stratégie : Stale-While-Revalidate
-
-Cette stratégie est **la clé de la performance** de l'application.
-
-#### Principe
-
-```
-Requête → Cache existe ?
-  ├─ Non    → Fetch normal + mise en cache
-  └─ Oui    → Cache valide ?
-      ├─ Oui    → Retourne immédiatement
-      └─ Non    → Retourne le cache expiré (stale)
-                  ET revalide en background
-```
-
-#### Implémentation
-
-```typescript
-async getOrSet<T>(
-  key: string,
-  fetcher: () => Promise<T>,
-  type: keyof typeof ServerCacheService.DEFAULT_TTL = "DEFAULT"
-): Promise<T> {
-  const cacheKey = `${user.id}-${key}`;
-  const cachedResult = this.getStale(cacheKey);
-
-  if (cachedResult !== null) {
-    const { data, isStale } = cachedResult;
-
-    // Si le cache est expiré, revalider en background
-    if (isStale) {
-      this.revalidateInBackground(cacheKey, fetcher, type, key);
-    }
-
-    return data as T; // Retour immédiat
-  }
-
-  // Pas de cache, fetch normal
-  const data = await fetcher();
-  this.set(cacheKey, data, type);
-  return data;
-}
-```
-
-#### Avantages
-
-✅ **Temps de réponse constant** : Le cache expiré est retourné instantanément  
-✅ **Données fraîches** : Revalidation en background pour la prochaine requête  
-✅ **Pas de délai** : L'utilisateur ne subit jamais l'attente de revalidation  
-✅ **Résilience** : Même si Komga est lent, l'app reste rapide
-
-#### Inconvénients
-
-⚠️ Les données peuvent être légèrement obsolètes (jusqu'au prochain refresh)  
-⚠️ Nécessite un cache initialisé (première requête toujours lente)
-
-### Modes de stockage
-
-L'utilisateur peut choisir entre deux modes :
-
-#### Mode Mémoire (par défaut)
-
-```typescript
-cacheMode: "memory";
-```
-
- Cache stocké en RAM
- **Performances** : Très rapide (lecture < 1ms)
- **Persistance** : Perdu au redémarrage du serveur
- **Capacité** : Limitée par la RAM disponible
- **Idéal pour** : Développement, faible charge
-
-#### Mode Fichier
-
-```typescript
-cacheMode: "file";
-```
-
- Cache stocké sur disque (`.cache/`)
- **Performances** : Rapide (lecture 5-10ms)
- **Persistance** : Survit aux redémarrages
- **Capacité** : Limitée par l'espace disque
- **Idéal pour** : Production, haute charge
-
-### Time-To-Live (TTL)
-
-Chaque type de données a un TTL configuré :
-
-| Type        | TTL par défaut | Justification                      |
-| ----------- | -------------- | ---------------------------------- |
-| `DEFAULT`   | 5 minutes      | Données génériques                 |
-| `HOME`      | 10 minutes     | Page d'accueil (données agrégées)  |
-| `LIBRARIES` | 24 heures      | Bibliothèques (rarement modifiées) |
-| `SERIES`    | 5 minutes      | Séries (métadonnées + progression) |
-| `BOOKS`     | 5 minutes      | Livres (métadonnées + progression) |
-| `IMAGES`    | 7 jours        | Images (immuables)                 |
-
-#### Configuration personnalisée
-
-Les TTL peuvent être personnalisés par l'utilisateur via la base de données :
-
-```typescript
-// Modèle Prisma : TTLConfig
-{
-  defaultTTL: 5 * 60 * 1000,
-  homeTTL: 10 * 60 * 1000,
-  librariesTTL: 24 * 60 * 60 * 1000,
-  seriesTTL: 5 * 60 * 1000,
-  booksTTL: 5 * 60 * 1000,
-  imagesTTL: 7 * 24 * 60 * 60 * 1000,
-}
-```
-
-### Isolation par utilisateur
-
-Chaque utilisateur a son propre cache :
-
-```typescript
-const cacheKey = `${user.id}-${key}`;
-```
-
-**Avantages** :
-
- Pas de collision entre utilisateurs
- Progression de lecture individuelle
- Préférences personnalisées
-
-### Invalidation du cache
-
-Le cache peut être invalidé :
-
-#### Manuellement
-
-```typescript
-await cacheService.delete(key); // Une clé
-await cacheService.deleteAll(prefix); // Toutes les clés avec préfixe
-await cacheService.clear(); // Tout le cache
-```
-
-#### Automatiquement
-
- Lors d'une mise à jour de progression
- Lors d'un changement de favoris
- Lors de la suppression d'une série
-
-#### API
-
-```
-DELETE /api/komga/cache/clear    // Vider tout le cache
-DELETE /api/komga/home           // Invalider le cache home
-```
-
-## Couche 3 : Cache HTTP (Navigateur)
-
-### Responsabilité
-
- Cache basique géré par le navigateur
- Headers HTTP standard
-
-### Configuration
-
-#### Next.js ISR (Incremental Static Regeneration)
-
-```typescript
-export const revalidate = 60; // Revalidation toutes les 60 secondes
-```
-
-Utilisé uniquement pour les routes avec rendu statique.
-
-#### Headers explicites (désactivé)
-
-Les headers HTTP explicites ont été **supprimés** car :
-
- Le ServerCacheService gère déjà le caching efficacement
- Évite la confusion entre plusieurs couches de cache
- Simplifie le debugging
-
-Avant (supprimé) :
-
-```typescript
-NextResponse.json(data, {
-  headers: {
-    "Cache-Control": "public, s-maxage=60, stale-while-revalidate=120",
-  },
-});
-```
-
-Maintenant :
-
-```typescript
-NextResponse.json(data); // Pas de headers
-```
-
-## Flow de données complet
-
-Exemple : Chargement de la page d'accueil
-
-```
-1. Utilisateur → GET /
-   ↓
-2. Next.js → HomeService.getHomeData()
-   ↓
-3. HomeService → ServerCacheService.getOrSet("home-ongoing", ...)
-   ↓
-4. ServerCacheService
-   ├─ Cache valide ? → Retourne immédiatement
-   ├─ Cache expiré ? → Retourne cache + revalide en background
-   └─ Pas de cache ? → Fetch Komga + mise en cache
-   ↓
-5. Response → Client
-   ↓
-6. Images → Service Worker (Cache-First)
-   ├─ En cache ? → Lecture instantanée
-   └─ Pas en cache ? → Fetch + mise en cache
-```
-
-### Temps de réponse typiques
-
-| Scénario                      | Temps       | Détails                    |
-| ----------------------------- | ----------- | -------------------------- |
-| Cache ServerCache valide + SW | ~50ms       | Optimal                    |
-| Cache ServerCache expiré + SW | ~50ms       | Revalidation en background |
-| Pas de cache ServerCache + SW | ~200-500ms  | Première requête           |
-| Cache SW uniquement           | ~10ms       | Images seulement           |
-| Tout à froid                  | ~500-1000ms | Pire cas                   |
-
-## Cas d'usage
-
-### 1. Première visite
-
-```
-User → App → Komga (tous les caches vides)
-Temps : ~500-1000ms
-```
-
-### 2. Visite suivante (online)
-
-```
-User → ServerCache (valide) → Images SW
-Temps : ~50ms
-```
-
-### 3. Cache expiré (online)
-
-```
-User → ServerCache (stale) → Retour immédiat
-       ↓
-       Revalidation background → Mise à jour cache
-Temps ressenti : ~50ms (aucun délai)
-```
-
-### 4. Mode offline
-
-```
-User → Service Worker cache uniquement
-Fonctionnalités :
-✅ Navigation entre pages déjà visitées
-✅ Consultation des images déjà vues
-❌ Nouvelles données (nécessite connexion)
-```
-
-## Monitoring et debug
-
-### Logs de cache (recommandé pour le dev)
-
-Activez les logs détaillés du cache serveur :
-
-```bash
-# Dans docker-compose.dev.yml ou .env
-CACHE_DEBUG=true
-```
-
-**Format des logs** :
-
-```
-[CACHE HIT] home-ongoing | HOME | 0.45ms      # Cache valide
-[CACHE STALE] home-ongoing | HOME | 0.52ms    # Cache expiré (retourné + revalidation)
-[CACHE MISS] home-ongoing | HOME              # Pas de cache
-[CACHE SET] home-ongoing | HOME | 324.18ms    # Mise en cache
-[CACHE REVALIDATE] home-ongoing | HOME | 287ms # Revalidation background
-```
-
-📖 **Documentation complète** : [docs/cache-debug.md](./cache-debug.md)
-
-### API de monitoring
-
-#### Taille du cache serveur
-
-```bash
-GET /api/komga/cache/size
-Response: { sizeInBytes: 15728640, itemCount: 234 }
-```
-
-#### Mode de cache actuel
-
-```bash
-GET /api/komga/cache/mode
-Response: { mode: "memory" }
-```
-
-#### Changer le mode
-
-```bash
-POST /api/komga/cache/mode
-Body: { mode: "file" }
-```
-
-#### Vider le cache
-
-```bash
-POST /api/komga/cache/clear
-```
-
-### DevTools du navigateur
-
-#### Network Tab
-
- Temps de réponse < 50ms = cache serveur
- Headers `X-Cache` si configurés
- Onglet "Timing" pour détails
-
-#### Application → Cache Storage
-
-Inspecter le Service Worker :
-
- `stripstream-cache-v1` : Ressources statiques
- `stripstream-images-v1` : Images
-
-Actions disponibles :
-
- Voir le contenu
- Supprimer des entrées
- Vider complètement
-
-#### Application → Service Workers
-
- État du Service Worker
- "Unregister" pour le désactiver
- "Update" pour forcer une mise à jour
-
-## Optimisations futures possibles
-
-### 1. Cache Redis (optionnel)
-
- Pour un déploiement multi-instances
- Cache partagé entre plusieurs serveurs
- TTL natif Redis
-
-### 2. Compression
-
- Compresser les données en cache (Brotli/Gzip)
- Économie d'espace disque/mémoire
- Trade-off CPU vs espace
-
-### 3. Prefetching intelligent
-
- Précharger les séries en cours de lecture
- Précharger les pages suivantes dans le reader
- Basé sur l'historique utilisateur
-
-### 4. Cache Analytics
-
- Ratio hit/miss
- Temps de réponse moyens
- Identification des données les plus consultées
-
-## Bonnes pratiques
-
-### Pour les développeurs
-
-✅ **Utiliser BaseApiService.fetchWithCache()**
-
-```typescript
-await this.fetchWithCache<T>(
-  "cache-key",
-  async () => this.fetchFromApi(...),
-  "HOME" // Type de TTL
-);
-```
-
-✅ **Invalider le cache après modification**
-
-```typescript
-await HomeService.invalidateHomeCache();
-```
-
-✅ **Choisir le bon TTL**
-
- Court (1-5 min) : Données qui changent souvent
- Moyen (10-30 min) : Données agrégées
- Long (24h+) : Données quasi-statiques
-
-❌ **Ne pas cacher les mutations**  
-Les POST/PUT/DELETE ne doivent jamais être cachés
-
-❌ **Ne pas oublier l'isolation utilisateur**  
-Toujours préfixer avec `userId` pour les données personnelles
-
-### Pour les utilisateurs
-
- **Mode mémoire** : Plus rapide, mais cache perdu au redémarrage
- **Mode fichier** : Persistant, idéal pour production
- **Vider le cache** : En cas de problème d'affichage
- **Offline** : Consulter les pages déjà visitées
-
-## Conclusion
-
-Le système de caching de StripStream est conçu pour :
-
-🎯 **Performance** : Temps de réponse constants grâce au stale-while-revalidate  
-🔒 **Fiabilité** : Fonctionne même si Komga est lent ou inaccessible  
-💾 **Flexibilité** : Mode mémoire ou fichier selon les besoins  
-🚀 **Offline-first** : Support complet du mode hors ligne  
-🧹 **Simplicité** : 3 couches bien définies, pas de redondance
-
-Le système est maintenu simple avec des responsabilités claires pour chaque couche, facilitant la maintenance et l'évolution future.
--- a/docs/services.md
+++ b/docs/services.md
@@ -7,10 +7,12 @@ Service de gestion de l'authentification
 ### Méthodes

 - `loginUser(email: string, password: string): Promise<UserData>`
+
  - Authentifie un utilisateur
  - Retourne les données utilisateur

 - `createUser(email: string, password: string): Promise<UserData>`
+
  - Crée un nouvel utilisateur
  - Retourne les données utilisateur

@@ -24,10 +26,11 @@ Service de gestion des bibliothèques
 ### Méthodes

 - `getLibraries(): Promise<Library[]>`
+
  - Récupère la liste des bibliothèques
-  - Met en cache les résultats

 - `getLibrary(libraryId: string): Promise<Library>`
+
  - Récupère une bibliothèque spécifique
  - Lance une erreur si non trouvée

@@ -47,9 +50,11 @@ Service de gestion des séries
 ### Méthodes

 - `getSeries(seriesId: string): Promise<Series>`
+
  - Récupère les détails d'une série

 - `getSeriesBooks(seriesId: string, page: number = 0, size: number = 24, unreadOnly: boolean = false): Promise<LibraryResponse<KomgaBook>>`
+
  - Récupère les livres d'une série
  - Supporte la pagination et le filtrage

@@ -63,15 +68,19 @@ Service de gestion des livres
 ### Méthodes

 - `getBook(bookId: string): Promise<{ book: KomgaBook; pages: number[] }>`
+
  - Récupère les détails d'un livre et ses pages

 - `updateReadProgress(bookId: string, page: number, completed: boolean = false): Promise<void>`
+
  - Met à jour la progression de lecture

 - `getPage(bookId: string, pageNumber: number): Promise<Response>`
+
  - Récupère une page spécifique d'un livre

 - `getCover(bookId: string): Promise<Response>`
+
  - Récupère la couverture d'un livre

 - `getPageThumbnail(bookId: string, pageNumber: number): Promise<Response>`
@@ -84,13 +93,15 @@ Service de gestion des images
 ### Méthodes

 - `getImage(path: string): Promise<ImageResponse>`
+
  - Récupère une image depuis le serveur
-  - Gère le cache des images

 - `getSeriesThumbnailUrl(seriesId: string): string`
+
  - Génère l'URL de la miniature d'une série

 - `getBookThumbnailUrl(bookId: string): string`
+
  - Génère l'URL de la miniature d'un livre

 - `getBookPageUrl(bookId: string, pageNumber: number): string`
@@ -103,29 +114,20 @@ Service de gestion de la configuration
 ### Méthodes

 - `getConfig(): Promise<Config>`
+
  - Récupère la configuration Komga

 - `saveConfig(config: Config): Promise<Config>`
+
  - Sauvegarde la configuration Komga

 - `getTTLConfig(): Promise<TTLConfig>`
+
  - Récupère la configuration TTL

 - `saveTTLConfig(config: TTLConfig): Promise<TTLConfig>`
  - Sauvegarde la configuration TTL

-## 🔄 ServerCacheService
-
-Service de gestion du cache serveur
-
-### Méthodes
-
- `getCacheMode(): string`
-  - Récupère le mode de cache actuel
-
- `clearCache(): void`
-  - Vide le cache serveur
-
 ## ⭐ FavoriteService

 Service de gestion des favoris
@@ -142,6 +144,7 @@ Service de gestion des préférences
 ### Méthodes

 - `getPreferences(): Promise<Preferences>`
+
  - Récupère les préférences utilisateur

 - `savePreferences(preferences: Preferences): Promise<void>`
@@ -164,13 +167,12 @@ Service de base pour les appels API
 ### Méthodes

 - `buildUrl(config: Config, path: string, params?: Record<string, string>): string`
+
  - Construit une URL d'API

 - `getAuthHeaders(config: Config): Headers`
+
  - Génère les en-têtes d'authentification

 - `fetchFromApi<T>(url: string, headers: Headers, raw?: boolean): Promise<T>`
  - Effectue un appel API avec gestion d'erreurs
-
- `fetchWithCache<T>(key: string, fetcher: () => Promise<T>, type: CacheType): Promise<T>`
-  - Effectue un appel API avec mise en cache