# Workflow recommandé : Dry-run puis Apply-from-CSV

## 🎯 Principe

Au lieu de re-scanner tous les films à chaque fois, utilisez le **workflow en 2 étapes** :

1. **Dry-run** : Scanne et génère le CSV (requêtes TMDB)
2. **Apply-from-CSV** : Applique les tags depuis le CSV (pas de requêtes TMDB)

**Avantages :**
- ✅ **Performance** : Pas de requêtes TMDB inutiles lors de l'application
- ✅ **Vérification** : Possibilité de vérifier/éditer le CSV avant application
- ✅ **Flexibilité** : Plusieurs tentatives d'application sans re-scanner
- ✅ **Rate limits** : Évite de spammer l'API TMDB

---

## 📋 Workflow complet

### Étape 1 : Dry-run (détection)

```bash
# Scanner tous les films (ou une limite)
python script.py --limit 100

# Ou tous les films
python script.py --limit 0
```

**Résultat :**
```
📄 CSV généré : results_spectacle_dryrun.csv
   → 15 spectacle(s) détectés sur 100 films analysés

🔒 Dry-run terminé. Pour appliquer les tags :
   OPTION 1 (RECOMMANDÉ) : Utiliser le CSV généré
     → python script.py --apply-from-csv
   OPTION 2 : Re-scanner et appliquer
     → python script.py --limit 100 --apply
```

---

### Étape 2 : Vérification du CSV (optionnel)

```bash
# Voir tous les spectacles détectés
cat results_spectacle_dryrun.csv | grep "True"

# Ou ouvrir dans Excel/LibreOffice
```

**Exemple CSV :**
```csv
title,year,tmdb_id,radarr_id,is_spectacle,score,reasons,excluded_by,runtime
Bérengère Krief - Le Trianon,2016,437722,194,True,18,runtime 71min; titre pattern ' - ' (+5); keyword 'stand-up' (+2),,71
Gad Elmaleh - Papa,2023,123456,195,True,16,runtime 75min; path contient 'spectacle' (+10),,75
```

**Actions possibles :**
- ✅ **Éditer le CSV** pour retirer des faux positifs
- ✅ **Ajouter manuellement** des spectacles (modifier `is_spectacle` à `True`)
- ✅ **Vérifier les scores** pour ajuster la config

---

### Étape 3 : Application depuis le CSV

```bash
# Appliquer les tags depuis le CSV (RECOMMANDÉ)
python script.py --apply-from-csv
```

**Résultat :**
```
📂 MODE APPLY-FROM-CSV : Chargement depuis le CSV du dry-run
   → Pas de requêtes TMDB, lecture du CSV uniquement

📥 Chargement du CSV : results_spectacle_dryrun.csv
   → 15 spectacle(s) chargé(s) depuis le CSV

📊 RÉSUMÉ : 15 spectacle(s) chargés depuis le CSV
  Spectacles à taguer :
    🎭 Bérengère Krief - Le Trianon (2016) — score=18
    🎭 Gad Elmaleh - Papa (2023) — score=16
    ...

🏷️  Application du tag (id=42) à 15 film(s)...
  ✅ Tag ajouté : 'Bérengère Krief - Le Trianon'
  ✅ Tag ajouté : 'Gad Elmaleh - Papa'
  ⏭️  Tag déjà présent : 'Florence Foresti - Motherfucker'
  ...

📊 Bilan : 12 ajouté(s), 3 déjà tagué(s), 0 erreur(s)

✅ Terminé. Tags appliqués depuis le CSV ! 🎭
```

---

## 🔄 Cas d'usage

### Cas 1 : Premier scan complet

```bash
# 1. Scanner toute la bibliothèque
python script.py --limit 0 --verbose

# 2. Vérifier le CSV
cat results_spectacle_dryrun.csv | grep "True"

# 3. Appliquer
python script.py --apply-from-csv
```

---

### Cas 2 : Test sur un échantillon

```bash
# 1. Tester sur 50 films
python script.py --limit 50

# 2. Vérifier les résultats
cat results_spectacle_dryrun.csv

# 3. Si OK, scanner tout
python script.py --limit 0

# 4. Appliquer
python script.py --apply-from-csv
```

---

### Cas 3 : Ajustement de la config

```bash
# 1. Scanner avec config actuelle
python script.py --limit 100

# 2. Trop de faux positifs → éditer config.yaml
vim config.yaml  # Ajouter keywords, changer sensitivity

# 3. Re-scanner (écrase le CSV précédent)
python script.py --limit 100

# 4. Appliquer la nouvelle détection
python script.py --apply-from-csv
```

---

### Cas 4 : Application partielle (édition manuelle du CSV)

```bash
# 1. Scanner
python script.py --limit 0

# 2. Éditer le CSV manuellement
# Retirer les faux positifs (changer True → False)
# Ajouter des spectacles manqués (changer False → True)
vim results_spectacle_dryrun.csv

# 3. Appliquer le CSV édité
python script.py --apply-from-csv
```

---

### Cas 5 : Re-application après erreur

```bash
# 1. Première tentative (erreur réseau ou Radarr down)
python script.py --apply-from-csv
# ❌ Erreur : 5 films taggés, 10 échoués

# 2. Corriger le problème (réseau, Radarr, etc.)

# 3. Re-lancer SANS re-scanner
python script.py --apply-from-csv
# Les films déjà taggés seront skippés automatiquement
```

---

## ⚠️ Avertissements

### CSV trop ancien

Si le CSV a plus de **24h**, un warning s'affiche :

```
⚠️  Le CSV a 2 jour(s). Les données TMDB peuvent avoir changé.
   → Recommandé : relancer un dry-run d'abord.
```

**Raison :** Les métadonnées TMDB peuvent changer (nouveaux keywords, runtime corrigé, etc.)

**Action :**
- Si les données TMDB sont stables → continuer avec `--apply-from-csv`
- Sinon → re-scanner d'abord

---

### Film supprimé de Radarr

Si un film du CSV n'existe plus dans Radarr :

```
⚠️  Film ID 123 (Titre du Film) non trouvé dans Radarr
```

**Raison :** Le film a été supprimé/déplacé entre le dry-run et l'application

**Action :** Ignoré automatiquement, pas d'erreur

---

### CSV manquant

Si le CSV n'existe pas :

```
❌ CSV introuvable : results_spectacle_dryrun.csv
   → Lance d'abord un dry-run : python script.py --limit 100
```

**Action :** Lancer un dry-run d'abord

---

## 🎯 Comparaison des modes

| Mode | Commande | Requêtes TMDB | Génère CSV | Applique tags |
|------|----------|---------------|------------|---------------|
| **Dry-run** | `python script.py --limit 100` | ✅ Oui | ✅ Oui | ❌ Non |
| **Apply direct** | `python script.py --limit 100 --apply` | ✅ Oui | ✅ Oui | ✅ Oui |
| **Apply from CSV** | `python script.py --apply-from-csv` | ❌ Non | ❌ Non | ✅ Oui |

---

## 📊 Performance

### Exemple : 1000 films

**Méthode classique (--apply) :**
```
Temps : ~45 minutes
- 1000 requêtes TMDB (GET /movie/{id})
- 1000 requêtes TMDB (GET /movie/{id}/keywords)
- Délai 0.25s entre chaque film
- Application des tags
```

**Méthode optimisée (dry-run + apply-from-csv) :**
```
Dry-run : ~45 minutes
- 1000 requêtes TMDB (GET /movie/{id})
- 1000 requêtes TMDB (GET /movie/{id}/keywords)
- Génération CSV

Apply-from-csv : ~30 secondes
- 0 requête TMDB ✅
- Lecture CSV
- Application des tags
```

**Gain si plusieurs tentatives :**
- 1 dry-run + 5 apply-from-csv : **48 minutes**
- 6 apply direct : **270 minutes** (4h30)

**Économie : 222 minutes (3h42) !** 🚀

---

## 💡 Conseils

### 1. Toujours faire un dry-run d'abord
```bash
# ❌ Mauvais (aucune vérification)
python script.py --limit 0 --apply

# ✅ Bon (vérification possible)
python script.py --limit 0
cat results_spectacle_dryrun.csv | grep "True"
python script.py --apply-from-csv
```

### 2. Garder l'historique des CSV
```bash
# Archiver les anciennes versions
cp results_spectacle_dryrun.csv backups/results_$(date +%Y%m%d).csv

# Nouveau scan
python script.py --limit 0

# Comparer avec l'ancien
diff backups/results_20260222.csv results_spectacle_dryrun.csv
```

### 3. Utiliser --verbose pour débugger
```bash
# Si un film n'est pas détecté
python script.py --limit 100 --verbose | grep "Titre du Film"
```

### 4. Éditer le CSV pour corrections manuelles
```bash
# Ouvrir dans un éditeur
vim results_spectacle_dryrun.csv

# Changer is_spectacle de True à False (faux positif)
# Ou de False à True (faux négatif)

# Appliquer les modifications
python script.py --apply-from-csv
```

---

## 🔧 Arguments disponibles

| Argument | Description | Exemple |
|----------|-------------|---------|
| `--limit N` | Nombre de films (0=tous) | `--limit 100` |
| `--apply` | Scanner + appliquer | `--apply --limit 0` |
| `--apply-from-csv` | Appliquer depuis CSV | `--apply-from-csv` |
| `--output FILE` | Nom du CSV | `--output mon_scan.csv` |
| `--verbose` | Logs détaillés | `--verbose` |
| `--quiet` | Logs minimaux | `--quiet` |

---

**Date :** 22 février 2026  
**Version :** 2.2 (ajout --apply-from-csv)  
**Statut :** ✅ Implémenté et documenté