oedb-backend/extractors/README_agendadulibre_improvements.md

# Améliorations du Scraper Agenda du Libre

## Nouvelles Fonctionnalités

### 1. Cache JSON Intelligent
- **Fichier de cache** : `agendadulibre_cache.json`
- **Détection de changements** : Le script détecte si le contenu iCal a changé via un hash MD5
- **Évite les re-téléchargements** : Si le contenu est identique, utilise le cache existant
- **Suivi des événements traités** : Mémorise les événements déjà traités pour éviter les doublons

### 2. Limitation du Nombre d'Événements
- **Argument `--max-events`** : Limite le nombre d'événements à traiter
- **Utile pour les tests** : Permet de tester avec un petit nombre d'événements
- **Statistiques** : Affiche le nombre d'événements ignorés à cause de la limite

### 3. Mode Dry-Run par Défaut
- **Sécurité** : Par défaut, aucun événement n'est envoyé à l'API
- **Simulation** : Affiche ce qui serait envoyé sans faire d'appels API réels
- **Override** : Utilisez `--no-dry-run` pour l'envoi réel

### 4. Logs Détaillés des Événements
- **Informations complètes** : Affiche tous les détails de l'événement avant insertion
- **Traçabilité** : ID, titre, description, dates, lieu, URL, source, etc.
- **Debugging** : Facilite le diagnostic des problèmes d'insertion
- **Audit** : Permet de vérifier les données avant envoi à l'API

### 5. Géocodage Automatique Intelligent
- **Priorité GEO** : Extrait d'abord les coordonnées du champ `GEO:` dans l'iCal
- **Détection d'adresses** : Extrait automatiquement les adresses après la première virgule
- **Géocodage Nominatim** : Utilise l'API Nominatim pour obtenir les coordonnées réelles
- **Nettoyage intelligent** : Détecte les numéros d'adresse pour améliorer la précision
- **Fallback robuste** : Utilise le lieu complet si pas d'adresse détectée
- **Respect des limites** : Pause d'1 seconde entre les requêtes Nominatim
- **Optimisation** : Évite le géocodage sur les événements déjà traités avec succès

### 6. Extraction des Catégories
- **Champ CATEGORIES** : Extrait automatiquement les catégories du champ `CATEGORIES:` de l'iCal
- **Tags multiples** : Support des catégories multiples par événement
- **Intégration OEDB** : Ajoute les catégories comme propriété `tags` dans l'événement
- **Logs informatifs** : Affiche les catégories trouvées dans les logs détaillés

### 7. Extraction des Propriétés Étendues
- **ORGANIZER** : Extrait l'organisateur de l'événement (email/contact)
- **X-ALT-DESC** : Extrait la description alternative HTML si disponible
- **SUMMARY** : Utilise le résumé comme description courte
- **SEQUENCE** : Extrait le numéro de séquence de l'événement
- **RRULE** : Extrait les règles de répétition pour les événements récurrents
- **Enrichissement complet** : Toutes les métadonnées iCal sont préservées

### 8. Priorisation des Événements
- **Événements en attente** : Priorité haute pour les événements avec status `pending`, `failed`, `api_error`
- **Cache intelligent** : Vérification dans les données locales et le cache
- **Tri automatique** : Les événements en attente sont traités en premier
- **Logs informatifs** : Indication claire des événements prioritaires avec emoji 🔄
- **Robustesse** : Retry automatique des événements échoués

### 9. Traitement Parallèle
- **Activation automatique** : Se déclenche pour plus de 10 événements avec `--parallel`
- **ThreadPoolExecutor** : Utilise `concurrent.futures` pour la parallélisation
- **Workers configurables** : Nombre de workers ajustable avec `--max-workers`
- **Thread-safe** : Méthode `process_single_event()` sécurisée pour les threads
- **Performance** : Amélioration significative pour les gros volumes d'événements

## Utilisation

### Commandes de Base

```bash
# Mode dry-run par défaut (sécurisé)
python agendadulibre.py

# Limiter à 5 événements en mode dry-run
python agendadulibre.py --max-events 5

# Mode réel avec limite de 10 événements
python agendadulibre.py --no-dry-run --max-events 10

# Mode verbeux pour voir les détails
python agendadulibre.py --max-events 3 --verbose

# Forcer le rechargement du fichier iCal
python agendadulibre.py --force-refresh --max-events 5

# Traitement parallèle pour gros volumes
python agendadulibre.py --max-events 50 --parallel --max-workers 8 --no-dry-run

# Traitement parallèle en mode dry-run
python agendadulibre.py --max-events 100 --parallel --max-workers 4
```

### Arguments Disponibles

| Argument | Description | Défaut |
|----------|-------------|---------|
| `--max-events N` | Limite le nombre d'événements à traiter | Aucune limite |
| `--dry-run` | Mode simulation (par défaut) | Activé |
| `--no-dry-run` | Désactive le mode dry-run | - |
| `--verbose` | Mode verbeux | - |
| `--force-refresh` | Force le rechargement iCal | - |
| `--cache-duration N` | Durée de validité du cache (heures) | 1 |
| `--batch-size N` | Taille des batches | 1 |
| `--api-url URL` | URL de l'API OEDB | https://api.openeventdatabase.org |
| `--parallel` | Activer le traitement parallèle pour plus de 10 événements | False |
| `--max-workers N` | Nombre maximum de workers pour le traitement parallèle | 4 |

## Fichiers Générés

### Cache JSON (`agendadulibre_cache.json`)
```json
{
  "processed_events": {
    "event_id_1": {
      "processed_at": "2024-01-01T12:00:00",
      "status": "saved",
      "event_label": "Nom de l'événement"
    }
  },
  "last_ical_fetch": "2024-01-01T12:00:00",
  "ical_content_hash": "md5_hash_du_contenu"
}
```

### Données d'Événements (`agendadulibre_events.json`)
```json
{
  "events": {
    "event_id": {
      "status": "saved",
      "message": "Créé avec succès",
      "last_attempt": "2024-01-01T12:00:00",
      "event": { /* données de l'événement */ }
    }
  },
  "last_update": "2024-01-01T12:00:00"
}
```

## Exemples de Sortie

### Mode Dry-Run avec Logs Détaillés
```
🚀 Démarrage du scraping de l'agenda du libre
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
Mode dry-run: OUI
Limite d'événements: 5
Cache iCal: valide pendant 1h
Mode DRY-RUN activé - aucun événement ne sera envoyé à l'API

📝 Détails de l'événement à insérer:
   ID: 6a575f6a82922f4501854431fc3f831c
   Titre: Conférence Python
   Description: Présentation sur Python
   Type: scheduled
   Catégorie: culture.floss
   Lieu: Paris, France
   Début: 2024-12-01T10:00:00
   Fin: 2024-12-01T12:00:00
   URL: https://example.com/event1
   Source: Agenda du Libre
   Coordonnées: [0, 0]
   Modifié par: agendadulibre_scraper
[DRY-RUN] Simulation d'envoi de l'événement: Conférence Python
✅ Conférence Python - Simulé (dry-run)
```

### Mode Réel avec Propriétés Complètes
```
🚀 Démarrage du scraping de l'agenda du libre
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
Mode dry-run: NON
Limite d'événements: 3

📍 Coordonnées GEO trouvées: 45.756, 4.84773
🏷️ Catégories trouvées: entraide, aldil, epn-des-rancy, linux
👤 Organisateur trouvé: mailto:contact@aldil.org
📝 Description courte trouvée: Entraide et Bidouille
🔢 Séquence trouvée: 3
✅ Coordonnées utilisées depuis le champ GEO: [4.84773, 45.756]

📝 Détails de l'événement à insérer:
   ID: 6a575f6a82922f4501854431fc3f831c
   Titre: Entraide et Bidouille
   Description: Atelier d'entraide informatique
   Type: scheduled
   Catégorie: culture.floss
   Lieu: Maison pour tous / salle des Rancy, 249 rue Vendôme, Lyon, France
   Début: 2024-12-01T10:00:00
   Fin: 2024-12-01T12:00:00
   URL: https://example.com/event1
   Source: Agenda du Libre
   Coordonnées: [4.84773, 45.756]
   Tags: entraide, aldil, epn-des-rancy, linux
   Organisateur: mailto:contact@aldil.org
   Description courte: Entraide et Bidouille
   Séquence: 3
   Règles de répétition: N/A
   Description HTML: N/A
   Modifié par: agendadulibre_scraper
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
✅ Événement créé avec succès dans l'API
✅ Entraide et Bidouille - Créé avec succès
```

### Mode Réel avec Géocodage Nominatim
```
🚀 Démarrage du scraping de l'agenda du libre
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
Mode dry-run: NON
Limite d'événements: 3

📍 Adresse potentielle trouvée: 15 rue de la Paix, Paris, France
🌍 Géocodage avec Nominatim: 15 rue de la Paix, Paris, France
✅ Géocodage réussi: 15 rue de la Paix, Paris, France -> (48.8566, 2.3522)
   Adresse trouvée: 15 Rue de la Paix, 75001 Paris, France
🎯 Coordonnées mises à jour par géocodage: [0, 0] -> [2.3522, 48.8566]

📝 Détails de l'événement à insérer:
   ID: 6a575f6a82922f4501854431fc3f831c
   Titre: Conférence Python
   Description: Présentation sur Python
   Type: scheduled
   Catégorie: culture.floss
   Lieu: Centre de conférences, 15 rue de la Paix, Paris, France
   Début: 2024-12-01T10:00:00
   Fin: 2024-12-01T12:00:00
   URL: https://example.com/event1
   Source: Agenda du Libre
   Coordonnées: [2.3522, 48.8566]
   Modifié par: agendadulibre_scraper
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
✅ Événement créé avec succès dans l'API
✅ Conférence Python - Créé avec succès
```

### Mode Optimisé - Événements Déjà Traités
```
🚀 Démarrage du scraping de l'agenda du libre
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
Mode dry-run: NON

⏭️ Événement ignoré: Conférence Python - déjà traité (status: saved)
⏭️ Événement ignoré: Atelier Linux - déjà dans le cache (status: saved)
ℹ️ Géocodage ignoré pour Formation Git - déjà traité
ℹ️ Géocodage ignoré - événement déjà traité
📝 Détails de l'événement à insérer:
   ID: dd0850de6ed7a6b4d482a7dc5201d09c
   Titre: Formation Git
   Description: Maîtriser Git
   Type: scheduled
   Catégorie: culture.floss
   Lieu: Espace formation, 42 avenue du Général de Gaulle, Marseille, France
   Début: 2024-12-03T09:00:00
   Fin: 2024-12-03T11:00:00
   URL: https://example.com/event3
   Source: Agenda du Libre
   Coordonnées: [5.3698, 43.2965]
   Modifié par: agendadulibre_scraper
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
⚠️ Événement déjà existant dans l'API
✅ Formation Git - Événement déjà existant
```

### Mode Prioritaire - Événements en Attente
```
🚀 Démarrage du scraping de l'agenda du libre
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
Mode dry-run: NON

🔄 Événement en attente prioritaire: Atelier Linux (status: failed)
🔄 Événement en attente du cache: Formation Git (status: pending)
📋 Événements à traiter: 2 (dont 2 en attente)
🔄 Traitement prioritaire: Atelier Linux
📝 Détails de l'événement à insérer:
   ID: 5ac96f4ae72cd28d164489580e97daca
   Titre: Atelier Linux
   Description: Apprendre Linux
   Type: scheduled
   Catégorie: culture.floss
   Lieu: Lyon, France
   Début: 2024-12-02T14:00:00
   Fin: 2024-12-02T16:00:00
   URL: https://example.com/event2
   Source: Agenda du Libre
   Coordonnées: [4.8357, 45.764]
   Modifié par: agendadulibre_scraper
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
✅ Événement créé avec succès dans l'API
✅ Atelier Linux - Créé avec succès
```

## Tests

Exécutez le script de test pour vérifier les fonctionnalités :

```bash
python test_agendadulibre_improvements.py
```

## Avantages

1. **Sécurité** : Mode dry-run par défaut évite les insertions accidentelles
2. **Performance** : Cache intelligent réduit les téléchargements inutiles
3. **Contrôle** : Limitation du nombre d'événements pour les tests
4. **Traçabilité** : Logs détaillés et fichiers de cache pour le suivi
5. **Flexibilité** : Arguments pour personnaliser le comportement
6. **Géolocalisation précise** : Géocodage automatique des lieux avec coordonnées réelles
7. **Intelligence** : Détection et extraction automatique des adresses
8. **Robustesse** : Fallback intelligent en cas d'échec de géocodage
9. **Optimisation** : Évite les retraitements inutiles des événements déjà envoyés
10. **Efficacité** : Skip automatique du géocodage pour les événements déjà traités
11. **Enrichissement** : Extraction automatique des catégories comme tags
12. **Classification** : Amélioration de la recherche et du filtrage des événements
13. **Métadonnées complètes** : Extraction de toutes les propriétés iCal importantes
14. **Traçabilité** : Organisateur, séquence et règles de répétition préservées
15. **Flexibilité** : Support des descriptions HTML et des événements récurrents
16. **Priorisation intelligente** : Traitement prioritaire des événements en attente
17. **Robustesse** : Retry automatique des événements échoués
18. **Efficacité** : Optimisation du traitement par priorité
19. **Parallélisation** : Traitement simultané pour les gros volumes d'événements
20. **Performance** : Amélioration significative avec `--parallel` et `--max-workers`

## Migration

Les anciens scripts continuent de fonctionner, mais il est recommandé d'utiliser les nouveaux arguments pour plus de contrôle et de sécurité.