Mangarr/assets/vue/app/domain/import/README.md

Domaine Import - Analyse et Import de Fichiers CBZ/CBR

Vue d'ensemble

Ce domaine permet l'import de fichiers CBZ/CBR dans Mangarr en utilisant l'analyse intelligente de noms de fichiers pour trouver automatiquement les correspondances avec les mangas de la bibliothèque.

Architecture

Structure des Dossiers

domain/import/
├── domain/
│   └── entities/
│       └── FileImport.js          # Entité représentant un fichier à importer
├── infrastructure/
│   └── api/
│       └── apiImportRepository.js # Client API
├── application/
│   └── store/
│       └── newImportStore.js      # Store Pinia principal
└── presentation/
    ├── pages/
    │   └── NewImportPage.vue      # Page principale d'import
    └── components/
        ├── FileImportCard.vue     # Carte de fichier à importer
        ├── ImportResults.vue      # Résumé des résultats
        └── StatusBadge.vue        # Badge de statut

Fonctionnalités

1. Upload de Fichiers

• Drag & Drop : Support du glisser-déposer pour les fichiers CBZ/CBR
• Sélection multiple : Import de plusieurs fichiers simultanément
• Validation : Vérification automatique des formats acceptés

2. Analyse Intelligente

• Extraction automatique : Le système analyse le nom de fichier pour extraire :

  • Le titre du manga
  • Le numéro de chapitre (si présent)
  • Le numéro de volume (si présent)

• Correspondance automatique :

  • Recherche des mangas correspondants dans la bibliothèque
  • Score de correspondance pour chaque résultat
  • Sélection automatique du meilleur match

3. Sélection et Validation

• Sélection de manga : Dropdown avec tous les mangas correspondants et leur score
• Prévisualisation : Affichage de la couverture et des informations du manga sélectionné
• Édition des numéros : Possibilité de modifier les numéros de chapitre/volume extraits
• Exclusivité : Un fichier ne peut être importé que comme chapitre OU volume (pas les deux)

4. Import

• Import unitaire : Import fichier par fichier
• Import groupé : Import de tous les fichiers prêts en une seule fois
• Retry : Possibilité de réessayer en cas d'erreur
• Suivi en temps réel : Indicateurs de progression et statuts

5. Résultats

• Statistiques : Nombre de fichiers importés, erreurs, total
• Détails : Liste des fichiers importés avec leurs associations
• Erreurs : Affichage détaillé des erreurs pour débogage

API Endpoints Utilisés

Analyse de fichiers

GET /api/manga-matches?filename={filename}

Retourne :

{
  "matches": [
    {
      "id": "string",
      "title": "string",
      "slug": "string",
      "alternativeSlugs": ["string"],
      "thumbnailUrl": "string",
      "matchScore": 100
    }
  ],
  "chapterNumber": 1.5,
  "volumeNumber": 2.0,
  "possibleTitles": ["string"]
}

Import de fichier

POST /api/chapters/import

FormData :

• file: Le fichier CBZ à importer
• mangaId: ID du manga
• chapterNumber: Numéro de chapitre (float, optionnel)

Réponse (200) :

{
  "message": "Chapter imported successfully",
  "mangaId": "uuid",
  "chapterNumber": 1.5
}

Erreurs :

• 404: Manga ou Chapitre non trouvé
• 422: Paramètres invalides ou fichier absent
• 400: Fichier CBZ invalide

Import de volume (À venir)

POST /api/volumes/import

FormData :

• file: Le fichier CBZ à importer
• mangaId: ID du manga
• volumeNumber: Numéro de volume (int)

Store Pinia

Le store newImportStore gère tout l'état de l'application :

État

• files: Liste des fichiers en cours de traitement
• analyzingFiles: Set des IDs de fichiers en analyse
• importingFiles: Set des IDs de fichiers en import
• isLoading: État de chargement global
• globalError: Erreur globale éventuelle

Getters

• pendingFiles: Fichiers en attente d'analyse
• analyzedFiles: Fichiers analysés
• readyFiles: Fichiers prêts pour l'import
• importedFiles: Fichiers importés avec succès
• errorFiles: Fichiers en erreur
• hasReadyFiles: Au moins un fichier prêt
• allFilesProcessed: Tous les fichiers traités
• progressPercentage: Pourcentage de progression

Actions Principales

• addFiles(fileList): Ajoute des fichiers et lance l'analyse automatique
• analyzeFile(fileId): Analyse un fichier spécifique
• setFileManga(fileId, manga): Définit le manga sélectionné
• setFileChapterNumber(fileId, number): Définit le numéro de chapitre
• setFileVolumeNumber(fileId, number): Définit le numéro de volume
• importFile(fileId): Importe un fichier
• importAllReadyFiles(): Importe tous les fichiers prêts
• autoSelectBestMatches(): Sélection automatique des meilleurs matchs
• retryFile(fileId): Réessaye l'analyse ou l'import d'un fichier

Entité FileImport

Représente un fichier dans le processus d'import :

Propriétés

• file: Objet File du navigateur
• filename: Nom du fichier original
• analysis: Résultat de l'analyse (matches, chapterNumber, volumeNumber)
• selectedManga: Manga sélectionné par l'utilisateur
• selectedChapterNumber: Numéro de chapitre (auto ou manuel)
• selectedVolumeNumber: Numéro de volume (auto ou manuel)
• status: pending | analyzed | importing | imported | error
• errorMessage: Message d'erreur le cas échéant

Méthodes Utiles

• hasMatches(): Vérifie si des correspondances ont été trouvées
• getMatches(): Retourne la liste des correspondances
• getBestMatch(): Retourne la meilleure correspondance
• isReadyForImport(): Vérifie si le fichier est prêt à être importé
• getImportData(): Prépare les données pour l'API d'import

Workflow Utilisateur

1. Upload: L'utilisateur glisse-dépose ou sélectionne des fichiers CBZ/CBR
2. Analyse automatique: Chaque fichier est analysé pour extraire les informations
3. Sélection auto: Le meilleur match est automatiquement sélectionné
4. Validation: L'utilisateur peut modifier le manga ou les numéros si nécessaire
5. Import: Import unitaire ou groupé des fichiers prêts
6. Résultats: Affichage du résumé avec succès et erreurs

Gestion des Erreurs

Erreurs d'analyse

• Aucun manga trouvé → Message informatif, possibilité de réessayer
• Erreur réseau → Message d'erreur, bouton retry disponible

Erreurs d'import

• Échec d'upload → Fichier marqué en erreur avec message détaillé
• Erreur serveur → Fichier en erreur, possibilité de retry

Améliorations Futures

1. Recherche manuelle : Permettre la recherche manuelle si aucun match
2. Multi-sélection : Sélectionner plusieurs fichiers pour actions groupées
3. Historique : Garder un historique des imports récents
4. Validation avancée : Vérifier si le chapitre/volume existe déjà
5. Métadonnées : Extraire et afficher plus de métadonnées des fichiers CBZ

Composants Réutilisables

Depuis Shared

• FileUpload.vue: Zone d'upload avec drag & drop
• LoadingSpinner.vue: Indicateur de chargement

Spécifiques au Domaine

• FileImportCard.vue: Carte complète de gestion d'un fichier
• StatusBadge.vue: Badge de statut avec couleurs
• ImportResults.vue: Résumé des résultats d'import