# Nuevas Funcionalidades - CampaignHub

## 🎯 Resumen de Implementación

Se han implementado **3 módulos principales** para mejorar las capacidades de análisis y seguimiento de campañas políticas:

1. **QR Regional Tracking** - Afiches políticos con seguimiento geográfico
2. **Social Monitoring** - Monitoreo de competencia en redes sociales
3. **Popularity Stats** - Estadísticas de popularidad y aceptación

---

## 1. 📍 QR Regional Tracking

### Descripción
Sistema completo para generar códigos QR para afiches políticos, rastrear quién los escanea por región y analizar intereses ciudadanos.

### Características Principales
- **Campañas de Afiches**: Crea campañas con diferentes tipos (posters, flyers, billboards, stickers, brochures)
- **Generación Masiva de QR**: Genera miles de códigos QR únicos con un solo clic
- **Tracking Regional**: Detecta ubicación del escaneo y territorio
- **Análisis de Engagement**: Mide clicks en CTAs, compartidos, tiempo en página
- **Intereses por Región**: Identifica qué temas generan más interés en cada zona
- **Heatmaps**: Visualiza concentración de escaneos en mapas

### Endpoints API

#### Crear Campaña de Afiches
```http
POST /api/poster-qr/campaigns
Content-Type: application/json

{
  "name": "Campaña Afiches Seguridad",
  "description": "Afiches sobre propuestas de seguridad",
  "type": "poster",
  "territory_id": 5,
  "start_date": "2024-01-15",
  "end_date": "2024-02-15",
  "total_posters": 500,
  "metadata": {
    "mensaje": "Seguridad para todos",
    "color_principal": "azul"
  }
}
```

#### Generar Códigos QR
```http
POST /api/poster-qr/campaigns/{id}/generate-codes

{
  "quantity": 500,
  "territory_id": 5,
  "base_url": "https://campaña.com/landing",
  "poster_batch": "Lote-001"
}
```

**Respuesta**: Lista de 500 códigos QR únicos con URLs individuales

#### Trackear Escaneo (Endpoint Público)
```http
POST /api/poster-qr/track-scan

{
  "code": "QR-ABC12345",
  "latitude": 4.60971,
  "longitude": -74.08175,
  "time_on_page": 45,
  "clicked_cta": true,
  "cta_action": "donar",
  "shared": true,
  "share_platform": "whatsapp"
}
```

**Uso**: Este endpoint se llama desde tu landing page cuando alguien escanea el QR.

#### Obtener Heatmap Regional
```http
GET /api/poster-qr/campaigns/{id}/heatmap

Respuesta:
{
  "interests": [
    {
      "territory_id": 5,
      "territory": { "name": "Centro" },
      "interest_type": "cta_action",
      "interest_value": "seguridad",
      "engagement_score": 450,
      "total_scans": 120,
      "total_cta_clicks": 80,
      "total_shares": 25
    }
  ],
  "scans": [
    {
      "scan_latitude": 4.60971,
      "scan_longitude": -74.08175,
      "territory_id": 5,
      "clicked_cta": true
    }
  ]
}
```

#### Analytics por Territorio
```http
GET /api/poster-qr/campaigns/{campaignId}/territory/{territoryId}

Respuesta:
{
  "total_scans": 120,
  "unique_visitors": 95,
  "engagement_rate": 67,
  "top_interests": [...],
  "scans_timeline": [
    { "date": "2024-01-15", "count": 25 },
    { "date": "2024-01-16", "count": 32 }
  ]
}
```

### Casos de Uso

**Ejemplo 1: Campaña de Afiches en Barrios**
1. Crea campaña con 1000 afiches
2. Genera 1000 códigos QR únicos
3. Imprime afiches con QR asignados por territorio
4. Voluntarios colocan afiches y reportan ubicación
5. Ciudadanos escanean → sistema registra ubicación
6. Dashboard muestra qué barrios tienen más interés
7. Ajustas estrategia según zonas con mejor respuesta

**Ejemplo 2: Detección de Intereses**
- Afiches sobre "Educación" en zona norte → 200 scans, 40% engagement
- Afiches sobre "Seguridad" en zona sur → 300 scans, 75% engagement
- **Insight**: Zona sur prioriza seguridad, zona norte educación
- **Acción**: Ajusta mensajes y eventos por zona

---

## 2. 🔍 Social Monitoring

### Descripción
Monitoreo completo de competencia política en redes sociales con análisis de sentimiento, alertas automáticas y comparativas.

### Características Principales
- **Registro de Competidores**: Agrega candidatos rivales y sus cuentas sociales
- **Recolección de Posts**: Almacena publicaciones de Facebook, Twitter, Instagram, TikTok, YouTube
- **Análisis con IA**: Clasificación de temas, sentimiento, detección de ataques
- **Alertas Automáticas**: Detecta picos de negatividad, ataques, crisis
- **Tendencias**: Identifica hashtags y palabras clave emergentes
- **Comparativas**: Compara engagement, followers, sentimiento entre candidatos

### Endpoints API

#### Dashboard de Monitoreo
```http
GET /api/social-monitoring/dashboard?days=7

Respuesta:
{
  "competitors_monitored": 5,
  "accounts_tracked": 15,
  "posts_collected": 342,
  "alerts_pending": 3,
  "alerts_critical": 1,
  "posts_by_platform": [
    { "platform": "facebook", "count": 120 },
    { "platform": "twitter", "count": 150 },
    { "platform": "instagram", "count": 72 }
  ],
  "sentiment_distribution": [
    { "ai_sentiment": "positive", "count": 180 },
    { "ai_sentiment": "neutral", "count": 120 },
    { "ai_sentiment": "negative", "count": 42 }
  ],
  "trending_topics": [...]
}
```

#### Agregar Competidor
```http
POST /api/social-monitoring/competitors

{
  "name": "María López",
  "party": "Partido Democrático",
  "level": "municipal",
  "jurisdiction": "Bogotá",
  "bio": "Candidata a alcaldía",
  "social_handles": {
    "facebook": "marialopez.oficial",
    "twitter": "@marialopez",
    "instagram": "marialopez_oficial",
    "tiktok": "@marialopez"
  }
}
```

#### Listar Posts
```http
GET /api/social-monitoring/posts?competitor_id=5&platform=facebook&sentiment=negative

Respuesta: Lista paginada de posts con:
- Contenido
- Métricas (likes, comments, shares)
- Análisis IA (sentimiento, temas, entidades)
- Clasificación (ataque, propuesta, fake news)
```

#### Reporte Comparativo
```http
GET /api/social-monitoring/comparison?days=30&competitors[]=1&competitors[]=2

Respuesta:
{
  "period_days": 30,
  "competitors": [
    {
      "competitor": { "id": 1, "name": "Juan Pérez", "party": "..." },
      "total_posts": 45,
      "total_engagement": 15420,
      "avg_engagement_rate": 3.2,
      "avg_sentiment": 0.45,
      "total_followers": 50000,
      "attacks": 5,
      "proposals": 12
    },
    {
      "competitor": { "id": 2, "name": "María López", "party": "..." },
      "total_posts": 38,
      "total_engagement": 18900,
      "avg_engagement_rate": 4.1,
      "avg_sentiment": 0.52,
      "total_followers": 48000,
      "attacks": 8,
      "proposals": 10
    }
  ]
}
```

#### Gestión de Alertas
```http
# Listar alertas
GET /api/social-monitoring/alerts?status=pending&severity=critical

# Actualizar alerta
PUT /api/social-monitoring/alerts/{id}
{
  "status": "in_progress",
  "assigned_to": 15,
  "response_notes": "Preparando comunicado de respuesta"
}
```

### Casos de Uso

**Ejemplo 1: War Room Digital**
- Dashboard muestra alertas en tiempo real
- Alerta crítica: Competidor publicó ataque
- Equipo revisa post, analiza impacto
- Asigna responsable para respuesta
- Publica aclaración en 30 minutos

**Ejemplo 2: Análisis de Competencia**
- Semanalmente revisa reporte comparativo
- Identifica que Competidor A tiene mejor engagement
- Analiza qué tipo de contenido usa
- Adapta estrategia de contenidos
- Mejora métricas propias

---

## 3. 📊 Popularity Stats

### Descripción
Sistema completo de medición de popularidad, encuestas, métricas diarias y análisis SWOT.

### Características Principales
- **Encuestas de Popularidad**: Registra resultados de encuestas internas y externas
- **Métricas Diarias/Semanales**: Agrega datos digitales, campo y financieros
- **Comparativas**: Compara posición vs competidores
- **Prioridades Ciudadanas**: Identifica temas que más importan por región
- **Análisis SWOT**: Fortalezas, debilidades, oportunidades, amenazas
- **Scores Compuestos**: Calcula popularidad combinando múltiples factores

### Endpoints API

#### Dashboard de Popularidad
```http
GET /api/popularity/dashboard?territory_id=5&days=30

Respuesta:
{
  "latest_poll": {
    "id": 10,
    "name": "Encuesta Enero 2024",
    "poll_date": "2024-01-20",
    "results": [
      {
        "candidate_name": "Juan Pérez",
        "vote_intention": 32.5,
        "favorability": 45.2,
        "rank": 1
      },
      {
        "candidate_name": "María López",
        "vote_intention": 28.3,
        "favorability": 41.8,
        "rank": 2
      }
    ]
  },
  "metrics_timeline": [...],
  "current_position": {
    "our_rank": 1,
    "our_score": 72.5,
    "gap_to_leader": 0,
    "is_leader": true,
    "closing_gap": false
  },
  "top_priorities": [
    {
      "issue": "seguridad",
      "priority_score": 85.3,
      "our_performance": 68.2,
      "competitor_best_performance": 72.1
    }
  ]
}
```

#### Registrar Encuesta
```http
POST /api/popularity/polls

{
  "name": "Encuesta Febrero 2024",
  "type": "external",
  "source": "Invamer",
  "territory_id": null,
  "poll_date": "2024-02-15",
  "sample_size": 1200,
  "margin_error": 2.8,
  "confidence_level": 95,
  "results": [
    {
      "candidate_name": "Juan Pérez",
      "vote_intention": 34.2,
      "favorability": 47.5,
      "unfavorability": 28.3,
      "recognition": 92.1
    },
    {
      "political_competitor_id": 2,
      "candidate_name": "María López",
      "vote_intention": 29.8,
      "favorability": 43.2,
      "unfavorability": 31.5,
      "recognition": 89.3
    }
  ]
}
```

#### Actualizar Métricas Diarias
```http
POST /api/popularity/metrics

{
  "metric_date": "2024-02-20",
  "period": "daily",
  "territory_id": null,
  "our_vote_intention": 34.2,
  "our_favorability": 47.5,
  "our_rank": 1,
  "social_followers_total": 52300,
  "social_followers_growth": 450,
  "social_engagement_total": 12500,
  "social_sentiment_avg": 0.52,
  "website_visits": 8500,
  "volunteer_signups": 23,
  "donations_count": 15,
  "donations_amount": 4500000,
  "door_knocks": 320,
  "events_attendance": 450,
  "pqrs_submitted": 28,
  "proposals_supported": 12
}
```

**El sistema calcula automáticamente**:
- `popularity_score`: Score 0-100 combinando encuestas (40%), digital (30%), campo (30%)
- `trend`: rising, stable, falling (comparando con período anterior)
- `momentum_score`: Diferencia vs período anterior

#### Análisis SWOT
```http
GET /api/popularity/swot?territory_id=5

Respuesta:
{
  "strengths": ["educacion", "juventud", "innovacion"],
  "weaknesses": ["seguridad", "infraestructura"],
  "opportunities": ["redes_sociales", "voluntariado_activo"],
  "threats": ["competidor_fuerte_en_seguridad", "baja_intencion_voto_rural"],
  "top_performing_issues": [
    {
      "issue": "educacion",
      "priority_score": 78.5,
      "our_performance": 72.3,
      "competitor_best_performance": 65.2
    }
  ],
  "improvement_needed": [
    {
      "issue": "seguridad",
      "priority_score": 89.2,
      "our_performance": 58.1,
      "competitor_best_performance": 74.5
    }
  ]
}
```

### Casos de Uso

**Ejemplo 1: Seguimiento Semanal**
- Lunes: Actualiza métricas de la semana
- Sistema calcula popularity_score: 68.5 (+2.3 vs semana anterior)
- Trend: "rising", momentum: +2.3
- Dashboard muestra evolución positiva
- Equipo identifica qué funcionó

**Ejemplo 2: Priorización de Temas**
- Análisis SWOT muestra:
  - Fortaleza en educación (72.3%)
  - Debilidad en seguridad (58.1%)
  - Seguridad es prioridad #1 ciudadana (89.2%)
- **Decisión**: Reforzar propuestas de seguridad
- Próximo evento enfocado en seguridad
- Nueva encuesta muestra mejora a 65.4%

---

## 🔧 Instalación y Configuración

### 1. Ejecutar Migraciones

```bash
# Migrar tenant (crea todas las tablas nuevas)
php artisan tenants:migrate
```

Esto creará 15 tablas nuevas:
- `poster_campaigns`, `poster_qr_codes`, `poster_qr_scans`, `regional_interests`
- `political_competitors`, `social_accounts`, `social_posts`, `social_comments`, `social_trends`, `social_alerts`
- `popularity_polls`, `poll_results`, `popularity_metrics`, `competitor_comparisons`, `citizen_priorities`

### 2. Configurar Permisos

```php
// En tu seeder o consola
use Spatie\Permission\Models\Permission;

Permission::create(['name' => 'manage_poster_qr']);
Permission::create(['name' => 'view_social_monitoring']);
Permission::create(['name' => 'manage_competitors']);
Permission::create(['name' => 'view_popularity_stats']);
Permission::create(['name' => 'manage_polls']);
```

### 3. Configurar Jobs (Opcional)

Para automatizar scraping de redes sociales:

```php
// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    // Scraping cada 6 horas
    $schedule->job(new ScrapeSocialAccountsJob())->everySixHours();
    
    // Calcular métricas diarias a medianoche
    $schedule->job(new CalculateDailyMetricsJob())->daily();
}
```

---

## 📱 Integración Frontend

### Ejemplo: Landing Page con QR Tracking

```html
<!-- landing.html -->
<!DOCTYPE html>
<html>
<head>
    <title>Únete a la Campaña</title>
</head>
<body>
    <h1>¡Gracias por tu interés!</h1>
    <p>Conoce nuestras propuestas...</p>
    
    <button id="btn-donar">Donar</button>
    <button id="btn-voluntario">Ser Voluntario</button>
    
    <script>
        // Obtener código QR de URL
        const params = new URLSearchParams(window.location.search);
        const qrCode = params.get('qr');
        const startTime = Date.now();
        
        // Obtener ubicación (con permiso)
        navigator.geolocation.getCurrentPosition(position => {
            const lat = position.coords.latitude;
            const lng = position.coords.longitude;
            
            // Trackear visita inmediatamente
            fetch('https://api.campaña.com/api/poster-qr/track-scan', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    code: qrCode,
                    latitude: lat,
                    longitude: lng
                })
            });
        });
        
        // Trackear click en CTA
        document.getElementById('btn-donar').addEventListener('click', () => {
            const timeOnPage = Math.floor((Date.now() - startTime) / 1000);
            
            fetch('https://api.campaña.com/api/poster-qr/track-scan', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    code: qrCode,
                    time_on_page: timeOnPage,
                    clicked_cta: true,
                    cta_action: 'donar'
                })
            });
            
            // Redirigir a página de donación
            window.location.href = '/donar';
        });
    </script>
</body>
</html>
```

---

## 🎯 Próximos Pasos

1. **Web Scraping Real**: Implementar scrapers para Facebook, Twitter, Instagram
2. **IA Real**: Integrar OpenAI/Anthropic para análisis de sentimiento
3. **Vistas Vue**: Crear dashboards interactivos
4. **Notificaciones**: Push notifications para alertas críticas
5. **Reportes PDF**: Exportar análisis en PDF
6. **Integración WhatsApp**: Enviar alertas por WhatsApp

---

## 📞 Soporte

- **Email**: support@campaignhub.com
- **Docs**: Ver `docs/api.md` para referencia completa de API
- **Issues**: Reporta bugs en GitHub

---

**¡Implementación Completa!** 🎉

Ahora tienes 3 módulos poderosos para:
1. Trackear interés ciudadano por región con QR
2. Monitorear competencia en redes sociales
3. Medir y analizar popularidad con métricas compuestas

**Total de endpoints nuevos**: 30+  
**Total de modelos nuevos**: 15  
**Total de tablas nuevas**: 15