# Social Media Scrapers - Guía Completa

## 📖 Resumen

Sistema completo de scraping de redes sociales para monitorear competencia política con análisis de sentimiento automático, detección de ataques y alertas en tiempo real.

### Plataformas Soportadas

- ✅ **Facebook** - Graph API v18.0
- ✅ **Twitter/X** - API v2
- ✅ **Instagram** - Graph API
- ✅ **TikTok** - Official API
- ✅ **YouTube** - Data API v3

---

## 🔧 Configuración

### 1. Variables de Entorno

Agrega estas variables a tu archivo `.env`:

```env
# Facebook/Meta Graph API
FACEBOOK_APP_ID=tu_app_id
FACEBOOK_APP_SECRET=tu_app_secret
FACEBOOK_ACCESS_TOKEN=tu_access_token
FACEBOOK_GRAPH_VERSION=v18.0

# Twitter/X API
TWITTER_API_KEY=tu_api_key
TWITTER_API_SECRET=tu_api_secret
TWITTER_BEARER_TOKEN=tu_bearer_token

# Instagram Graph API
INSTAGRAM_APP_ID=tu_app_id
INSTAGRAM_APP_SECRET=tu_app_secret
INSTAGRAM_ACCESS_TOKEN=tu_access_token

# TikTok API
TIKTOK_CLIENT_KEY=tu_client_key
TIKTOK_CLIENT_SECRET=tu_client_secret
TIKTOK_ACCESS_TOKEN=tu_access_token

# YouTube Data API v3
YOUTUBE_API_KEY=tu_api_key

# AI Services (Opcional)
OPENAI_API_KEY=tu_openai_key
ANTHROPIC_API_KEY=tu_anthropic_key
```

### 2. Obtener API Keys

#### Facebook/Instagram

1. Ve a https://developers.facebook.com/
2. Crea una App de tipo "Business"
3. Agrega productos: "Facebook Login" y "Instagram Basic Display"
4. Obtén el App ID y App Secret
5. Genera un Access Token de larga duración:
   ```bash
   curl -X GET "https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id=TU_APP_ID&client_secret=TU_APP_SECRET&fb_exchange_token=TU_SHORT_TOKEN"
   ```

#### Twitter/X

1. Ve a https://developer.twitter.com/
2. Crea un proyecto y una App
3. Obtén las credenciales en "Keys and tokens"
4. Activa permisos de lectura
5. Copia el Bearer Token

#### YouTube

1. Ve a https://console.cloud.google.com/
2. Crea un proyecto
3. Habilita "YouTube Data API v3"
4. Crea credenciales (API Key)
5. Restringe la key a YouTube Data API v3

#### TikTok

1. Ve a https://developers.tiktok.com/
2. Crea una App
3. Solicita acceso a "Display API" y "Video API"
4. Obtén Client Key y Client Secret
5. Genera Access Token con OAuth 2.0

---

## 🚀 Uso

### Opción 1: Comando Artisan (Manual)

```bash
# Scrapear una cuenta específica
php artisan social:scrape --account=5

# Scrapear todas las cuentas de una plataforma
php artisan social:scrape --platform=facebook

# Scrapear todas las cuentas activas
php artisan social:scrape --all

# Limitar posts a scrapear
php artisan social:scrape --account=5 --limit=100
```

### Opción 2: Jobs Programados (Automático)

Configura en `app/Console/Kernel.php`:

```php
protected function schedule(Schedule $schedule)
{
    // Scraping cada 6 horas
    $schedule->job(new ScrapeAllSocialAccountsJob())
        ->everySixHours()
        ->withoutOverlapping();
    
    // Actualizar tendencias diarias
    $schedule->command('social:update-trends')
        ->daily();
}
```

### Opción 3: Dispatchar Job Manualmente

```php
use App\Jobs\ScrapeSocialAccountJob;
use App\Models\SocialAccount;

$account = SocialAccount::find(1);
ScrapeSocialAccountJob::dispatch($account, 50);
```

### Opción 4: Via API

```bash
# Crear competidor y cuenta social
curl -X POST http://localhost:8000/api/social-monitoring/competitors \
  -H "Authorization: Bearer tu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María López",
    "party": "Partido Democrático",
    "level": "municipal",
    "social_handles": {
      "facebook": "marialopez.oficial",
      "twitter": "@marialopez",
      "instagram": "marialopez_oficial"
    }
  }'

# El sistema automáticamente creará las cuentas sociales
# y comenzará a scrapear según el horario configurado
```

---

## 📊 Características

### 1. Análisis de Sentimiento Automático

Cada post es analizado automáticamente:

```php
$post->ai_sentiment; // 'very_positive', 'positive', 'neutral', 'negative', 'very_negative'
$post->ai_sentiment_score; // -1.0 a 1.0
```

**Basado en**:
- Palabras clave positivas/negativas
- Contexto del mensaje
- Tono general

### 2. Detección de Temas

Extrae automáticamente temas relevantes:

```php
$post->ai_topics; // ['seguridad', 'educacion', 'salud']
```

**Temas detectados**:
- Seguridad
- Educación
- Salud
- Empleo
- Movilidad
- Ambiente
- Vivienda
- Cultura

### 3. Detección de Ataques

Identifica posts que contienen ataques a otros candidatos:

```php
$post->is_attack; // true/false
```

**Palabras clave**: mentira, corrupto, ladrón, incompetente, fracasado

### 4. Detección de Propuestas

Identifica posts que contienen propuestas:

```php
$post->is_proposal; // true/false
```

**Palabras clave**: propongo, propuesta, vamos a, haremos, construir, mejorar

### 5. Alertas Automáticas

El sistema crea alertas automáticamente cuando:

- Se detecta un ataque
- Sentimiento muy negativo con alto engagement
- Pico repentino de engagement (3x el promedio)

```php
// Ver alertas
GET /api/social-monitoring/alerts?status=pending&severity=critical

// Respuesta
{
  "data": [
    {
      "type": "attack",
      "severity": "high",
      "title": "Ataque detectado",
      "description": "Post de María López contiene un ataque",
      "status": "new",
      "detected_at": "2024-02-20 10:30:00"
    }
  ]
}
```

---

## 📈 Análisis y Reportes

### 1. Dashboard de Monitoreo

```bash
GET /api/social-monitoring/dashboard?days=7
```

Muestra:
- Total de posts recolectados
- Distribución por plataforma
- Distribución de sentimientos
- Engagement por competidor
- Trending topics

### 2. Comparativa de Competidores

```bash
GET /api/social-monitoring/comparison?days=30&competitors[]=1&competitors[]=2
```

Compara:
- Total de posts
- Engagement total y promedio
- Sentimiento promedio
- Followers
- Ataques vs propuestas

### 3. Timeline de Sentimiento

```bash
GET /api/social-monitoring/sentiment/5?days=30
```

Muestra evolución de sentimiento día a día.

### 4. Tendencias

```bash
GET /api/social-monitoring/trends?days=7&platform=twitter
```

Hashtags y palabras clave más mencionadas.

---

## 🔄 Flujo de Scraping

```
1. Comando/Cron ejecuta Job
   ↓
2. Job obtiene cuenta de SocialAccount
   ↓
3. Selecciona Scraper según plataforma
   ↓
4. Scraper llama a API de red social
   ↓
5. Parsea respuesta y extrae datos
   ↓
6. Análisis automático (sentimiento, temas, ataques)
   ↓
7. Guarda posts en database
   ↓
8. Actualiza métricas de cuenta
   ↓
9. Scrapea comentarios (si tiene alto engagement)
   ↓
10. Evalúa si debe crear alertas
   ↓
11. Crea alertas automáticas si aplica
   ↓
12. Marca cuenta como scrapeada
```

---

## 🛡️ Manejo de Errores

### Rate Limiting

Los scrapers manejan automáticamente rate limits:

- **Retry automático**: 3 intentos con backoff exponencial
- **Delay entre requests**: 1-10 segundos aleatorios
- **Headers de rate limit**: Lee y respeta headers de la API

### Errores de API

Si una cuenta falla:

```php
$account->scraping_status; // 'error'
$account->scraping_error; // "API returned 401: Unauthorized"
```

El sistema NO detiene el scraping de otras cuentas.

### Logging

Todos los eventos se registran:

```bash
tail -f storage/logs/laravel.log | grep "social"
```

---

## 💡 Ejemplos de Uso

### Ejemplo 1: Monitorear 5 Competidores

```php
// 1. Registrar competidores
$competidores = [
    ['name' => 'Juan Pérez', 'facebook' => 'juanperez.oficial'],
    ['name' => 'María López', 'twitter' => '@marialopez'],
    ['name' => 'Carlos Ruiz', 'instagram' => 'carlosruiz'],
];

foreach ($competidores as $data) {
    $competitor = PoliticalCompetitor::create([
        'name' => $data['name'],
        'status' => 'active',
    ]);
    
    if (isset($data['facebook'])) {
        SocialAccount::create([
            'political_competitor_id' => $competitor->id,
            'platform' => 'facebook',
            'handle' => $data['facebook'],
        ]);
    }
}

// 2. Ejecutar scraping
ScrapeAllSocialAccountsJob::dispatch();

// 3. Ver resultados después de 10 minutos
$stats = SocialPost::where('posted_at', '>=', now()->subDays(7))
    ->selectRaw('political_competitor_id, COUNT(*) as posts, AVG(ai_sentiment_score) as sentiment')
    ->groupBy('political_competitor_id')
    ->get();
```

### Ejemplo 2: Alertas de Crisis

```php
// Configurar webhook para alertas críticas
SocialAlert::where('severity', 'critical')
    ->where('status', 'new')
    ->each(function ($alert) {
        // Enviar notificación a Slack/WhatsApp/Email
        Notification::send($warRoomTeam, new CriticalSocialAlertNotification($alert));
    });
```

### Ejemplo 3: Reporte Semanal

```php
// Generar reporte PDF semanal
$report = [
    'period' => 'Semana del 12-18 Feb 2024',
    'our_stats' => [
        'posts' => 15,
        'avg_engagement' => 2500,
        'sentiment' => 0.65,
    ],
    'competitors' => SocialPost::whereIn('political_competitor_id', [1,2,3])
        ->where('posted_at', '>=', now()->subWeek())
        ->groupBy('political_competitor_id')
        ->get(),
];

PDF::loadView('reports.social-weekly', $report)->save('weekly-social.pdf');
```

---

## ⚡ Optimizaciones

### 1. Colas

Usa colas para no bloquear requests:

```bash
php artisan queue:work --queue=social-scraping
```

### 2. Caché

Los scrapers cachean resultados por 5 minutos para evitar llamadas duplicadas.

### 3. Batch Processing

Scrapea máximo 50 posts por cuenta para evitar timeouts.

### 4. Incremental Scraping

Solo scrapea posts nuevos (no duplica posts existentes).

---

## 🔐 Seguridad

### API Keys

- **Nunca** commitees las API keys al repositorio
- Usa variables de entorno
- Rota tokens cada 3 meses

### Rate Limits

Respeta los límites de cada plataforma:

- Facebook: 200 calls/hour
- Twitter: 300 calls/15min
- Instagram: 200 calls/hour
- YouTube: 10,000 units/day
- TikTok: Varía según plan

### Privacidad

- Solo scrapea cuentas públicas
- No almacena datos personales sensibles
- Cumple con términos de servicio de cada plataforma

---

## 📞 Soporte

- **Documentación**: `docs/nuevas-funcionalidades.md`
- **API Reference**: `docs/api.md`
- **Issues**: Reporta bugs en GitHub

---

## 🎯 Próximos Pasos

1. **Integración con IA real**: OpenAI/Anthropic para análisis avanzado
2. **Scraping de threads**: Hilos completos de Twitter
3. **Análisis de imágenes**: Detectar contenido visual
4. **Predicción de viralidad**: ML para predecir qué posts se viralizarán
5. **Auto-respuestas**: Sugerencias de respuestas basadas en IA

---

**¡Scrapers listos para usar!** 🚀

Ahora puedes monitorear a tu competencia 24/7 con análisis automático.