# Twitter Scraper

Module de scraping Twitter avec gestion des rate limiting et mode dégradé.

## Fonctionnalités

- ✅ Collecte de tweets pour les matchs de football
- ✅ Rate limiting (1000 req/heure) avec alertes prédictives (>90%)
- ✅ Mode dégradé avec priorisation des matchs VIP
- ✅ Retry avec backoff exponentiel
- ✅ Logging structuré pour monitoring
- ✅ Stockage en base de données partagée

## Installation

```bash
pip install tweepy==4.14.0
```

## Configuration

Variables d'environnement requises:

```bash
# Twitter API Bearer Token
TWITTER_BEARER_TOKEN="your_bearer_token_here"
```

## Utilisation

### Exemple de base

```python
from app.scrapers.twitter_scraper import create_twitter_scraper
from app.database import SessionLocal

# Créer le scraper
scraper = create_twitter_scraper(
    bearer_token="your_bearer_token",
    vip_match_ids=[1, 2, 3]  # Matchs VIP pour mode dégradé
)

# Scrapper des tweets pour un match
db = SessionLocal()
try:
    tweets = scraper.scrape_and_save(
        match_id=1,
        keywords=["#MatchName", "Team1 vs Team2"],
        db=db,
        max_results=100
    )
    print(f"✅ {len(tweets)} tweets collectés")
finally:
    db.close()
```

### Configuration avancée

```python
from app.scrapers.twitter_scraper import TwitterScraper

scraper = TwitterScraper(
    bearer_token="your_bearer_token",
    max_tweets_per_hour=1000,  # Limite par défaut
    rate_limit_alert_threshold=0.9,  # Alert à 90%
    vip_match_ids=[1, 2, 3, 4, 5]
)
```

## Architecture

### Rate Limiting

Le scraper implémente:
- **Tracking en temps réel** des appels API
- **Alertes prédictives** quand la limite est atteinte à >90%
- **Mode dégradé automatique** quand la limite est atteinte
- **Backoff exponentiel** pour éviter les blocages

### Mode Dégradé

Quand le rate limit est atteint:
- Le scraper passe en mode VIP seulement
- Seuls les matchs VIP sont scrapés
- Alertes loggées pour monitoring
- Les données sont sauvegardées avant arrêt

## Tests

Exécuter les tests:

```bash
cd backend
pytest tests/test_twitter_scraper.py -v
```

## Intégration

Le module s'intègre avec:
- **SQLite**: Base de données partagée avec Next.js
- **SQLAlchemy**: ORM pour le backend FastAPI
- **Drizzle ORM**: ORM pour le frontend Next.js
- **RabbitMQ** (Phase 2+): Queue asynchrone pour découplage

## Conventions de Code

- **Nommage Python**: `snake_case`
- **Nommage Base de données**: `snake_case`
- **Logging**: Structuré avec `logging` module
- **Type hints**: Obligatoires avec `typing`

## Documentation API

Voir [documentation Tweepy](https://docs.tweepy.org/) pour plus de détails sur l'API Twitter.

## Dépannage

### Erreur: "Twitter API authentication failed"

Vérifiez votre bearer token:
```python
client.get_me()  # Devrait retourner vos infos utilisateur
```

### Rate limit atteint trop rapidement

Vérifiez l'utilisation:
```python
print(f"API calls: {scraper.api_calls_made}/{scraper.max_tweets_per_hour}")
```

### Mode dégradé activé sans raison

Vérifiez les seuils:
```python
print(f"Usage: {scraper.rate_limit_info.usage_percentage * 100:.1f}%")
```

## Prochaines Étapes

- [ ] Intégration avec RabbitMQ (Phase 2)
- [ ] Système de priorisation dynamique
- [ ] Dashboard de monitoring en temps réel
- [ ] Tests d'intégration E2E