# Instructions pour la refonte du Lead Pipeline (Phase 1 : Discovery & Enrichment)

Tu es un développeur Python Senior expert en architecture asynchrone et en automatisation B2B. Ton objectif est de construire la première partie d'un pipeline de génération de leads local, performant et résilient.

## 1. Objectif de la Phase 1

Créer un outil CLI en Python (avec `Typer`) capable de tourner en tâche de fond ou à la demande. Ce script doit :

1. Prendre en entrée une `niche` et une `region`.
2. Trouver des prospects (Discovery).
3. Analyser leur site pour trouver le dirigeant et auditer leur SEO/Performance (Enrichment).
4. Pousser ces données structurées dans EspoCRM avant toute démarche d'emailing.

## 2. Stack Technique

- **Python 3.X+** (Gestion d'environnement via `uv` ou `mise`).
- **Framework CLI :** `typer` (avec `rich` pour l'affichage console).
- **Requêtes HTTP :** `httpx` (plus moderne et stable qu'`aiohttp` pour les API REST).
- **Base de données :** `aiosqlite` (ou `SQLAlchemy` async) pour l'anti-doublon et la gestion d'état.
- **Validation :** `pydantic` pour les modèles de données.

## 3. Architecture "State Machine" (Asynchrone)

Le script ne doit pas être un flux linéaire bloquant. Chaque prospect passe par des états dans SQLite. Des "workers" asynchrones traitent les prospects en fonction de leur état.

**Les états SQLite (`local_status`) :**

- `new` : Requête de recherche générée.
- `discovered` : URL trouvée, domaine extrait, anti-doublon passé.
- `enriched` : Scrape Firecrawl + Audit Lighthouse terminés.
- `synced_crm` : Données poussées dans EspoCRM.

## 4. Logique Métier

### Étape 1 : Discovery (Firecrawl Search)

- **Input :** `niche` (ex: "piscines"), `region` (ex: "Bretagne").
- **Action :** Construire des requêtes de recherche depuis un `config/niches.yaml` (ex: "constructeur piscine Bretagne contact").
- **Exécution :** Appel à l'API Firecrawl (`/v1/search`).
- **Filtre :** Extraction du nom de domaine. Vérification stricte en base de données locale (SQLite) : si le domaine existe déjà, on ignore (anti-doublon absolu).
- **Output :** Insertion en DB avec `local_status = 'discovered'`.

### Étape 2 : Enrichment (Firecrawl Scrape + PageSpeed API)

Prendre les leads au statut `discovered` par lots de 10.

- **Action A (Contact & Stack) :** Scrape Firecrawl sur l'URL pour identifier le nom du dirigeant et la technologie du site (ex: WordPress, Next.js).
- **Action B (Audit SEO/Perf) :** Appel à l'API Google PageSpeed Insights (endpoint `https://www.googleapis.com/pagespeedonline/v5/runPagespeed`).
  - Extraire le score SEO, score Performance, LCP (Largest Contentful Paint), et vérifier si les Core Web Vitals passent.
- **Scoring ICP :** Calculer un score sur 100 (ex: +20 si LCP > 4s, +20 si dirigeant trouvé).
- **Output :** Mise à jour en DB avec `local_status = 'enriched'`.

### Étape 3 : EspoCRM Setup & Sync

- **Prérequis EspoCRM (à documenter) :** Le CRM doit avoir de nouveaux champs personnalisés créés via l'UI Admin : `cLighthouseScore`, `cMissingSeo`, `cLcpTime`, `cTechStack`, `cNiche`, `cRegion`.
- **Action :** Pousser les leads `enriched` vers l'API REST d'EspoCRM (`POST /api/v1/Lead`).
- **Mapping :** Assigner le statut `New` ou `Researching` dans le CRM.
- **Output :** Récupérer l'`id` généré par EspoCRM, le sauvegarder dans SQLite, et passer `local_status = 'synced_crm'`.

## 5. Interface CLI attendue

Implémente ces commandes Typer :

- `pipeline run --niche "salles_de_sport" --region "Occitanie" --limit 20` : Lance un batch spécifique.
- `pipeline daemon` : Boucle infinie qui lit `config.yaml` et traite toutes les niches/régions en respectant des temps de pause (rate limits).
- `pipeline status` : Affiche un tableau récapitulatif des leads par état dans SQLite.

## 6. Contraintes d'implémentation

- Utilise un logger structuré (`structlog`) avec sortie JSON dans un fichier et sortie lisible dans le terminal.
- Gère les Rate Limits de Firecrawl et Google de manière élégante (backoff exponentiel avec `tenacity`).
- Ne gère **pas** la partie Email Finder pour le moment. Concentre-toi sur la robustesse de l'extraction et la synchro CRM.