v0.1.0 — Réécriture complète de OhmStreaming

Nouvelle version réécrite de zéro : recherche multi-sources (Vostfree,
French-Manga), extraction 2 niveaux, proxy vidéo intégré, streaming/téléchargement
HLS, métadonnées Kitsu, bibliothèque locale, comptes JWT + administration,
découverte fusionnée, indexeur Torznab (Sonarr/Prowlarr).

Projet_descriptions.md

@@ -0,0 +1,96 @@
+# Ohm Stream Downloader — Description fonctionnelle
+
+> Cahier des charges pour une réécriture à partir de zéro.
+
+## 🎯 Le but du projet
+
+Une **application web auto-hébergée** (pensée pour un homelab, usage personnel) qui sert de **centre de contrôle unique** pour les contenus vidéo en français (animes, séries TV, VOSTFR) :
+
+1. **Découvrir** du contenu en cherchant sur plusieurs sites/sources en même temps,
+2. **Regarder** directement dans l'application via un lecteur intégré,
+3. **Télécharger** des épisodes ou des saisons complètes,
+4. **Ne rien rater** : suivre des titres et télécharger automatiquement chaque nouvel épisode dès sa sortie.
+
+L'application agrège donc le rôle de moteur de recherche, de plateforme de streaming, de gestionnaire de téléchargements et d'outil d'automatisation.
+
+## 👤 Parcours utilisateur type
+
+1. L'utilisateur se connecte (ou s'inscrit).
+2. Il lance une **recherche unifiée** : une seule requête interroge tous les sites d'animes et de séries activés, les résultats sont fusionnés.
+3. Il consulte la **fiche détaillée** d'un titre : poster, bannière, synopsis, genres, note, année, nombre d'épisodes, liste des saisons et épisodes.
+4. Depuis la fiche, il peut :
+   - **streamer** un épisode dans le lecteur intégré,
+   - **télécharger** un épisode précis ou une **saison entière** d'un coup,
+   - **l'ajouter à sa watchlist** pour un suivi automatique,
+   - **l'ajouter aux favoris**.
+5. Il suit l'avancement des téléchargements en temps réel, puis **regarde les fichiers téléchargés** dans une bibliothèque locale (streaming depuis le serveur, reprise de lecture, épisode suivant).
+
+## ⚙️ Fonctionnalités détaillées
+
+### 1. Recherche multi-sources
+- Sources « animes » : environ 5 sites francophones (Anime-Sama, Neko-Sama, Anime-Ultime, Vostfree, French-Manga).
+- Sources « séries/films » : environ 2 sites (FS7/French-Stream, Zone-Téléchargement).
+- Chaque source est un **module interchangeable** avec le même contrat : chercher, lister les épisodes, récupérer les métadonnées, extraire le lien vidéo réel.
+- Résolution automatique : pour une URL donnée, le système trouve tout seul le bon module (site → hébergeur vidéo → générique).
+- **Extraction en 2 niveaux** : la page de l'épisode contient des lecteurs embarqués hébergés ailleurs (une quinzaine d'hébergeurs supportés : DoodStream, VidMoly, 1fichier, Uptobox, Sibnet, Uqload, SendVid, etc.). Le système sait résoudre l'URL directe du fichier pour chacun d'eux.
+
+### 2. Métadonnées enrichies
+- Les infos de base viennent du site scrappé, puis sont **enrichies/complétées** via une base externe de données anime (Kitsu, en alternative à MAL) : synopsis, genres, notes, année, images.
+- Fusion intelligente : on ne remplit que les champs manquants, avec normalisation des formats entre sources.
+- **Cache des métadonnées** pour limiter les appels externes.
+
+### 3. Streaming et lecteur
+- Lecteur vidéo intégré pour les liens extraits des hébergeurs (avec contournement des protections courantes de ces hébergeurs).
+- **Bibliothèque locale** : tous les fichiers téléchargés sont streamables depuis le serveur (page « watch » avec reprise de lecture, navigation épisode suivant, streaming avec support des requêtes de plage pour l'avance rapide).
+
+### 4. Gestionnaire de téléchargements
+- File d'attente avec **téléchargements parallèles limités** (~3–5 simultanés).
+- Statuts : en attente, en cours, en pause, terminé, échec, annulé.
+- **Pause / reprise** (via requêtes de plage HTTP), **retry**, **annulation**, « tout annuler », nettoyage des tâches finies.
+- **Progression temps réel** : pourcentage, vitesse, temps restant — rafraîchie dynamiquement côté interface.
+- **Anti-doublons** : si un téléchargement de la même source est déjà actif/en attente, on retourne la tâche existante au lieu d'en créer une.
+- **Persistance** : au démarrage, le dossier de téléchargements est scanné pour **restaurer** les tâches terminées.
+- Noms de fichiers **nettoyés et sécurisés** automatiquement (suppression de caractères interdits, protection contre la traversée de répertoires).
+- Les URLs circulent au format interne `video_url|page_url|titre` pour ne pas perdre le contexte entre l'extraction et le téléchargement.
+
+### 5. Watchlist + téléchargement automatique (le cœur de l'app)
+- L'utilisateur suit un titre ; chaque item a un **statut** : actif, en pause, terminé, archivé.
+- Mémorisation du **dernier épisode téléchargé** et du dernier épisode disponible.
+- Un **planificateur interne** vérifie périodiquement (intervalle configurable, d'1 h à 168 h) tous les titres « dus » :
+  - détecte les nouveaux épisodes par comparaison au dernier connu,
+  - les **télécharge automatiquement**,
+  - journalise un rapport (nouveaux épisodes trouvés / téléchargés).
+- Réglages globaux de la watchlist (activation de l'auto-download, intervalle, etc.), statistiques de suivi.
+- Vérification manuelle possible à la demande (« vérifier maintenant »).
+
+### 6. Intégration Sonarr (homelab)
+- Réception de **webhooks Sonarr** (événements type « épisode importé/téléchargé ») avec **vérification d'authenticité** (signature HMAC + secret) optionnelle.
+- **Mapping entre séries Sonarr et sources de scraping** : pour chaque série suivie dans Sonarr, on associe le titre/URL correspondant sur un site d'animes, pour que Sonarr déclenche le téléchargement dans la bonne source.
+- Endpoints d'aide : recherche Sonarr, recherche d'épisodes, **suggestions automatiques de mapping**, configuration (langue, qualité, provider par défaut, activation du webhook, journalisation).
+
+### 7. Favoris
+- Sauvegarde de titres aimés avec leurs métadonnées et images, avec statistiques et pagination/navigation.
+
+### 8. Recommandations et découvertes
+- **Analyse de l'historique de téléchargement** (parsing des noms de fichiers pour extraire titres, groupes, saisons, qualité) → profil de goûts (genres, titres) → **suggestions personnalisées**.
+- Sections découverte : **dernières sorties**, **sorties saisonnières**, **calendrier des sorties**, **top** actuel.
+
+### 9. Comptes et administration
+- Inscription/connexion/déconnexion avec **sessions par tokens** (token court + refresh token longue durée).
+- Rôles **admin / utilisateur**, activation/désactivation de comptes.
+- Interface d'**administration** : liste des utilisateurs, stats, bascule admin/actif, suppression.
+
+### 10. Paramètres et gestion des sources
+- **Activation/désactivation de chaque source** individuellement (sans redémarrage), avec état de **santé** vérifiable (test manuel + contrôle automatique périodique par le planificateur).
+- Réglages de l'interface utilisateur, configuration persistée.
+- Endpoints publics de santé de l'application et liste des sources disponibles.
+
+## 🧩 Principes de conception pour la réécriture
+
+- **Architecture à 3 niveaux de scrapers** : sites de catalogues (animes / séries) → hébergeurs vidéo → extraction générique. Chaque niveau a une classe de base et un registre ; ajouter une nouvelle source = écrire un module qui implémente le contrat et le déclarer dans le registre. *Point le plus important : les sites changent souvent, il faut pouvoir en ajouter un en une heure.*
+- **Configuration de scraping externalisée** : piloter au moins certaines sources par fichier de configuration (sélecteurs), pour réparer un site cassé sans toucher au code.
+- **Un seul format interne** pour transporter le contexte (`vidéo|page|titre`) du scraping jusqu'au téléchargement.
+- **Sécurité non négociable** : nettoyage systématique des noms de fichiers, secrets hors fichiers de config, tokens signés.
+- **Une seule source de vérité** pour les données (pas de double stockage JSON + base).
+- **Pas d'erreurs silencieuses** : chaque échec de scraping/téléchargement est journalisé et exposé (statut d'échec visible dans l'UI).
+- **Injection de dépendances** entre les composants (vérificateur d'épisodes ↔ gestionnaire de téléchargements) pour éviter les dépendances circulaires.