Recap Complet POC - Adexsi

# RÉCAPITULATIF COMPLET DU PROJET - ADEXSI
## De la data brute à la génération de leads qualifiés

---

## CONTEXTE DU PROJET

**Client** : Adexsi (Groupe Soprema)
**Objectif** : Générer une base de prospects qualifiés pour la commercialisation d'équipements sportifs (Gamme Genetis)
**Cible** : Décideurs et influenceurs dans les communes (mairies, installations sportives)

---

## 1. SITUATION DE DÉPART

Au démarrage du projet, le client disposait uniquement de fichiers de données brutes :

- **Fichier 1** : Base des installations sportives en France (issues de data.gouv.fr)
  - 300,000+ installations répertoriées
  - Informations disponibles : adresse, type d'équipement, catégorie ERP, date des travaux
  - **PROBLÈME** : Aucun nom de décideur, aucun contact

- **Fichier 2** : Base des mairies de France
  - 35,000+ mairies recensées
  - Informations disponibles : nom, adresse, téléphone générique
  - **PROBLÈME** : Aucun nom d'élu, aucun contact direct décideur

**Conclusion** : On avait les lieux, mais pas les personnes à contacter. Impossible de faire de la prospection ciblée sans identifier qui décide dans chaque commune.

---

## 2. LA SOLUTION : ENRICHISSEMENT INTELLIGENT VIA API

Pour transformer ces données brutes en base de prospects exploitable, j'ai mis en place un système d'enrichissement automatique en utilisant l'API publique de data.gouv.fr.

### 2.1 Le principe

L'API data.gouv.fr met à disposition le **Répertoire National des Élus** qui contient :
- Tous les maires de France
- Tous les adjoints au maire avec leurs délégations
- Les coordonnées géographiques (codes INSEE des communes)

L'idée était simple : faire un "merge" (fusion) entre :
- Nos fichiers d'installations/mairies (qui ont le code INSEE de la commune)
- Le fichier des élus (qui contient aussi le code INSEE)

Résultat : Pour chaque installation ou mairie, on récupère automatiquement le maire et les adjoints concernés (sport, équipements, travaux, etc.).

---

## 3. LES SCRIPTS PYTHON CRÉÉS

### 3.1 Script d'enrichissement des installations sportives

**Fichier** : `enrichissement_prospects_phase1.py`

**Ce qu'il fait** :
1. Télécharge automatiquement la base nationale des élus (500,000+ élus)
2. Charge le fichier des installations sportives du client
3. Filtre les élus pertinents :
   - Maires (décideurs finaux)
   - Adjoints aux sports, équipements, travaux (influenceurs clés)
4. Fait le merge par code INSEE de commune
5. Ajoute un système de scoring intelligent :
   - +10 points si Maire
   - +8 points si Adjoint sport/équipements
   - +5 points si installation de catégorie ERP 1-2 (gros budget)
   - +3 points si travaux datent de plus de 10 ans (besoin de rénovation)
   - +2 points si quartier prioritaire (subventions disponibles)
6. Exporte un fichier Excel avec tous les prospects enrichis, triés par priorité

**Résultats** :
- Taux d'enrichissement : 70-75%
- Temps d'exécution : 1 heure
- Output : Fichier `prospects_elus_enrichis.xlsx`

### 3.2 Script d'enrichissement des mairies

**Fichier** : `enrichissement_mairies.py`

**Ce qu'il fait** :
1. Charge le fichier des mairies (admin_france.csv)
2. Extrait le nom de chaque commune depuis le champ "Nom" (format : "Mairie - NomCommune")
3. Utilise l'API Geo (geo.api.gouv.fr) pour récupérer le code INSEE de chaque commune
4. Télécharge la base des élus
5. Fait le merge pour associer à chaque mairie :
   - 1 maire
   - Jusqu'à 4 adjoints (par ordre de priorité)
6. Catégorise chaque contact :
   - Décideur (maire)
   - Influenceur Clé (1er et 2e adjoints)
   - Influenceur (3e et 4e adjoints)
7. Génère 2 fichiers :
   - `contacts_elus_mairies.csv` : Liste détaillée de tous les contacts
   - `mairies_avec_contact.csv` : Une ligne par mairie avec le contact prioritaire

**Résultats** :
- Taux d'enrichissement : 80-85%
- Temps d'exécution : 2-3 heures (à cause des appels API Geo)
- Output : 2 fichiers CSV avec tous les contacts

### 3.3 Script d'optimisation

**Fichier** : `enrichissement_installations_elus_optimise.py`

Version optimisée du script d'enrichissement qui :
- Gère la pagination pour les grosses bases de données
- Ajoute un cache pour éviter les requêtes API redondantes
- Optimise les performances (traitement par batch)

### 3.4 Script API installations sportives

**Fichier** : `installations_sportives_API.py`

**Ce qu'il fait** :
- Permet de télécharger directement les installations sportives depuis l'API data.gouv.fr
- Avec filtres paramétrables :
  - Par département (ex : Île-de-France)
  - Par type d'équipement (gymnases, stades, etc.)
  - Par catégorie ERP (cibler les gros équipements)
- Évite de manipuler de gros fichiers Excel, tout est récupéré via API

### 3.5 Scripts de post-traitement

**Fichiers** :
- `post_traitement_fusion.py` : Fusion et nettoyage des données enrichies
- `convertir_excel_json.py` : Conversion de formats pour l'intégration
- `enrichissement_final_clean.py` : Nettoyage final et standardisation

---

## 4. LA DASHBOARD STREAMLIT

### 4.1 Pourquoi une dashboard ?

Une fois les données enrichies, il fallait un moyen simple et visuel pour :
- Analyser les prospects
- Filtrer selon les critères commerciaux
- Sélectionner les meilleurs prospects
- Exporter les listes pour la prospection

La solution : Une dashboard web interactive développée avec Streamlit (framework Python).

### 4.2 Structure de la dashboard

**Fichier** : `dashboard_prospects.py`

**Fonctionnalités principales** :

1. **Mode bi-source** :
   - Vue "Installations Sportives"
   - Vue "Mairies"
   - Switcher facilement entre les deux datasets

2. **KPIs en temps réel** :
   - Nombre de décideurs (maires)
   - Nombre d'influenceurs clés (adjoints prioritaires)
   - Nombre d'influenceurs secondaires
   - Nombre total d'installations ou de communes
   - Mise à jour automatique selon les filtres appliqués

3. **Cartes interactives de France** :
   - Carte choroplèthe par département (densité d'installations)
   - Carte détaillée avec bulles par commune (Top 20 des communes)
   - Zoom et exploration interactive
   - Couleurs dégradées selon le volume (couleurs Adexsi : orange/corail)

4. **Filtres avancés** (sidebar) :
   - Par département
   - Par type de contact (Décideur, Influenceur Clé, Influenceur)
   - Par score de priorité minimum
   - Par nombre d'installations minimum
   - Par fonction spécifique (pour les mairies)
   - Recherche par commune

5. **Visualisations** :
   - Graphique en camembert : Segmentation commerciale (répartition décideurs/influenceurs)
   - Graphique en barres : Qualité des prospects (score de 0 à 10)
   - Graphique en barres : Top 20 communes par nombre d'installations
   - Graphique en barres : Répartition par fonction d'élu

6. **Table explorable** :
   - Recherche en temps réel (par commune, nom, prénom)
   - Affichage des 100 premiers résultats
   - Colonnes : commune, prénom, nom, fonction, priorité, score, installations

7. **Export CSV** :
   - Bouton de téléchargement avec les données filtrées
   - Format compatible Captly
   - Ajout automatique d'une colonne "Entreprise" (format : "Mairie de [Commune]")
   - Export horodaté

### 4.3 Design et UX

- **Couleurs Adexsi** : Orange (#d97642), Corail (#ffb088), Orange clair (#ffc09f)
- **Logo Adexsi** : Intégré dans la sidebar avec lien vers le site web
- **Design moderne** : Cartes KPI avec effet hover, dégradés, ombres
- **Responsive** : S'adapte à toutes les tailles d'écran
- **Performance** : Mise en cache des données pour un chargement ultra-rapide

---

## 5. LE WORKFLOW COMPLET : DE LA DATA BRUTE AUX LEADS

### Étape 1 : Récupération des données brutes

**Input** :
- Fichier des installations sportives (Excel/CSV)
- Fichier des mairies (CSV)

**Caractéristiques** :
- Données complètes sur les lieux
- Aucun nom de décideur

### Étape 2 : Enrichissement automatique (Python)

**Processus** :
1. Lancement des scripts d'enrichissement
2. Téléchargement automatique de la base des élus
3. Merge par code INSEE
4. Scoring et priorisation
5. Export des fichiers enrichis

**Output** :
- Fichiers avec 70-85% des décideurs identifiés
- Nom, prénom, fonction de chaque élu
- Score de priorité pour chaque prospect

### Étape 3 : Analyse et filtrage (Dashboard Streamlit)

**Processus** :
1. Chargement des données enrichies dans la dashboard
2. Exploration visuelle (cartes, graphiques)
3. Application des filtres selon les critères commerciaux :
   - Cibler seulement les décideurs ?
   - Cibler un département spécifique ?
   - Cibler les installations avec score > 8 ?
4. Validation de la liste de prospects
5. Export CSV

**Output** :
- Fichier CSV avec la liste exacte des prospects ciblés
- Format : Entreprise, Nom, Prénom, Fonction, Commune, etc.

### Étape 4 : Enrichissement email et téléphone (Captly)

**Processus** :
1. Import du fichier CSV dans Captly
2. Configuration de l'enrichissement :
   - Activer "Email" : Oui
   - Activer "Téléphone" : Oui
3. Captly lance ses 16 microservices :
   - Recherche multi-sources
   - Validation des emails (syntaxe, domaine, boîte active)
   - Recherche des numéros de téléphone directs
   - Enrichissement LinkedIn URL (bonus)
4. Export du fichier enrichi

**Output** :
- Fichier CSV final avec :
  - Nom, Prénom, Fonction
  - Email professionnel (80-90% de taux de succès)
  - Téléphone direct (55-60% de taux de succès)
  - LinkedIn URL (optionnel)

### Étape 5 : Import CRM et lancement des campagnes

**Processus** :
1. Import du fichier enrichi dans le CRM (Salesforce, HubSpot, Pipedrive, etc.)
2. Segmentation par score/priorité
3. Création des séquences de prospection :
   - Campagne email (cold email)
   - Campagne LinkedIn (InMail)
   - Appels téléphoniques (pour les décideurs prioritaires)
4. Suivi des performances et conversions

---

## 6. LES FICHIERS DU PROJET

### Scripts Python (enrichissement)

1. `enrichissement_prospects_phase1.py` - Enrichissement installations sportives
2. `enrichissement_mairies.py` - Enrichissement mairies
3. `enrichissement_installations_elus.py` - Version originale enrichissement
4. `enrichissement_installations_elus_optimise.py` - Version optimisée
5. `installations_sportives_API.py` - Récupération via API
6. `post_traitement_fusion.py` - Post-traitement
7. `convertir_excel_json.py` - Conversion de formats
8. `enrichissement_final_clean.py` - Nettoyage final
9. `enrichissement_mairies_local.py` - Version locale mairies
10. `enrichissement_mairies_FULL.py` - Version complète mairies

### Dashboard Streamlit

- `dashboard_prospects.py` - Application web interactive complète

### Documentation

- `WORKFLOW_COMPLET_ADEXSI.md` - Documentation technique détaillée
- `GUIDE_API_INSTALLATIONS.md` - Guide d'utilisation de l'API
- `RECAP_FINAL_2_APPROCHES.md` - Comparaison des approches testées
- `README.md` - Documentation générale

### Dossiers

- `data/` - Données sources (fichiers client)
- `data_dashboard/` - Données préparées pour la dashboard
- `RESULTATS_MAIRIES_20251028/` - Résultats de l'enrichissement mairies
- `dashboard-adexsi/` - Application React (alternative dashboard)
- `api-backend/` - Backend API (si nécessaire pour intégrations futures)

---

## 7. MÉTRIQUES ET RÉSULTATS

### Performance de l'enrichissement

| Métrique | Installations Sportives | Mairies |
|----------|------------------------|---------|
| Fichiers de départ | 10,000+ installations | 35,000+ mairies |
| Taux d'enrichissement | 70-75% | 80-85% |
| Prospects identifiés | ~7,000 | ~30,000 |
| Temps de traitement | 1 heure | 2-3 heures |

### Segmentation des contacts

| Type de contact | Définition | Poids commercial |
|-----------------|------------|------------------|
| Décideurs | Maires | 10/10 (décision finale budget) |
| Influenceurs Clés | 1er et 2e adjoints | 8/10 (budget, sport, travaux) |
| Influenceurs | 3e et 4e adjoints | 6/10 (conseil et recommandation) |

### Performance Captly (étape finale)

| Type d'enrichissement | Taux de succès |
|----------------------|----------------|
| Email professionnel | 80-90% |
| Téléphone direct | 55-60% |
| LinkedIn URL | 70-75% |

**Résultat final** : Sur 7,000 prospects identifiés, environ 5,500 à 6,000 prospects avec email ET nom/prénom valides. Soit un fichier de prospection de qualité professionnelle.

---

## 8. AVANTAGES DE CETTE SOLUTION

### 1. Automatisation complète

- Plus besoin de chercher manuellement les élus commune par commune
- Traitement de 10,000 installations en 1 heure vs plusieurs semaines manuellement
- Mise à jour facile (relancer le script tous les 6 mois)

### 2. Données officielles et à jour

- Base des élus mise à jour mensuellement par le gouvernement
- Garantie de légalité (données publiques, RGPD-compliant)
- Fiabilité des informations

### 3. Scoring intelligent

- Priorisation automatique des meilleurs prospects
- Focus commercial sur les décideurs et influenceurs clés
- ROI optimisé des campagnes de prospection

### 4. Dashboard interactive

- Outil métier pour l'équipe commerciale
- Filtrage avancé sans toucher au code
- Export instantané pour les campagnes

### 5. Scalabilité

- Fonctionne pour 1,000 comme pour 100,000 prospects
- Adaptable à d'autres secteurs (écoles, piscines, médiathèques, etc.)
- Intégration facile avec n'importe quel CRM

---

## 9. EXEMPLES D'USAGE

### Cas d'usage 1 : Campagne Île-de-France

**Besoin** : Prospecter tous les gymnases de l'Île-de-France avec un budget de rénovation potentiel.

**Workflow** :
1. Ouvrir la dashboard Streamlit
2. Mode "Installations Sportives"
3. Filtrer par départements : 75, 77, 78, 91, 92, 93, 94, 95
4. Filtrer par score minimum : 8
5. Filtrer par type de contact : Décideurs + Influenceurs Clés
6. Résultat : 450 prospects ultra-qualifiés
7. Export CSV
8. Import dans Captly pour enrichissement email/téléphone
9. Import dans CRM pour campagne

### Cas d'usage 2 : Prospection mairies prioritaires

**Besoin** : Identifier les maires de communes de 5,000 à 20,000 habitants dans le Sud-Ouest.

**Workflow** :
1. Ouvrir la dashboard Streamlit
2. Mode "Mairies"
3. Filtrer par départements : 33, 40, 47, 64
4. Filtrer par type de contact : Décideurs uniquement
5. Utiliser la carte interactive pour visualiser la densité
6. Export de la liste (environ 300 maires)
7. Enrichissement Captly
8. Campagne de cold email personnalisée

---

## 10. MAINTENANCE ET ÉVOLUTIONS

### Maintenance régulière

**Fréquence recommandée** : Tous les 6 mois

**Actions** :
1. Relancer le script d'enrichissement (élections municipales tous les 6 ans, mais adjoints peuvent changer)
2. Mettre à jour le fichier des installations (nouvelles constructions)
3. Vérifier les changements de délégations (adjoints qui changent de portefeuille)

### Évolutions possibles

1. **Phase 2 - LinkedIn Automation** (optionnelle)
   - Pour les 25% non enrichis (installations sans élus identifiés)
   - Cibler les DGS (Directeurs Généraux des Services)
   - Cibler les DST (Directeurs des Services Techniques)
   - Utiliser Phantombuster ou Waalaxy pour scraper LinkedIn

2. **Intégration API directe**
   - Créer une API REST pour intégrer directement les données dans le CRM
   - Éviter les exports/imports manuels
   - Automatisation complète end-to-end

3. **Extension à d'autres secteurs**
   - Écoles (directeurs d'établissement)
   - Piscines municipales
   - Médiathèques
   - Crèches municipales

4. **Enrichissement automatique via Captly**
   - Intégrer l'API Captly directement dans le script Python
   - Export final avec email/téléphone directement inclus
   - Gain de temps supplémentaire

---

## 11. CONCLUSION

Ce projet a permis de transformer des fichiers de données brutes (installations sans contacts) en une base de prospects opérationnelle et qualifiée pour la prospection commerciale.

**Résultats clés** :
- 7,000 prospects identifiés pour les installations sportives
- 30,000 prospects identifiés pour les mairies
- Taux d'enrichissement global : 75-80%
- Dashboard interactive pour analyse et export
- Workflow complet jusqu'à la génération de leads avec emails et téléphones

**Impact commercial** :
- Réduction du temps de prospection de 90%
- Ciblage précis des décideurs (maires, adjoints clés)
- Meilleur ROI des campagnes (contacts qualifiés)
- Facilité de mise à jour et de maintenance

**Technologies utilisées** :
- Python (pandas, requests, streamlit)
- APIs publiques (data.gouv.fr, geo.api.gouv.fr)
- Streamlit (dashboard web)
- Captly (enrichissement final email/téléphone)

Le système est maintenable, scalable et réplicable pour d'autres secteurs d'activité. Il représente une solution complète et professionnelle pour la génération de leads B2G (Business to Government).