# Sistema de QR Tracking + Captura de Datos - Guía Completa

## 🎯 Descripción

Sistema **ultra completo** para:
1. **Generar QR únicos** para cada afiche político
2. **Trackear ubicación** de quien escanea
3. **Capturar datos personales** (con consentimiento Ley 1581)
4. **Analizar por territorio** qué zonas tienen más apoyo
5. **Comparar con competencia** usando datos reales
6. **Convertir leads** en voluntarios/donantes
7. **Seguimiento post-captura** (llamadas, visitas, eventos)

---

## 🚀 Flujo Completo

```
1. CREAR CAMPAÑA
   ↓
2. GENERAR QR (1000 códigos únicos)
   ↓
3. IMPRIMIR AFICHES con QR
   ↓
4. COLOCAR AFICHES en territorios
   ↓
5. CIUDADANO escanea QR
   ↓
6. LANDING PAGE captura datos
   ↓
7. SISTEMA ANALIZA por territorio
   ↓
8. EQUIPO hace seguimiento
   ↓
9. LEAD se convierte en voluntario/donante
   ↓
10. COMPARATIVA vs competencia
```

---

## 📊 Tablas Creadas

### 1. `qr_citizen_leads`
**Almacena datos de ciudadanos** que escanearon QR

Campos principales:
- **Datos personales**: nombre, email, teléfono, documento, fecha nacimiento, género
- **Ubicación**: dirección, barrio, ciudad, lat/lng
- **Intereses**: qué temas le importan (seguridad, educación, etc.)
- **Nivel de apoyo**: muy_interesado, interesado, neutral, poco_interesado
- **Quiere**: ser voluntario, donar, recibir updates
- **Consentimientos**: procesamiento datos, contacto, compartir (Ley 1581)

### 2. `qr_lead_interactions`
**Registro de seguimiento** a cada lead

Tipos: llamada, email, WhatsApp, visita, invitación evento, encuesta

### 3. `qr_lead_conversions`
**Cuando un lead se convierte** en algo

Tipos: voluntario, donante, asistente evento, voto confirmado, compartió en redes

### 4. `territory_demographic_profiles`
**Análisis demográfico agregado** por territorio

- Distribución por género, edad, nivel socioeconómico
- Intereses principales
- Tasa de conversión
- Score de apoyo

---

## 🔧 Configuración

### 1. Ejecutar Migración

```bash
php artisan tenants:migrate
```

### 2. Crear Campaña de Afiches

```bash
POST /api/poster-qr/campaigns

{
  "name": "Afiches Febrero 2024",
  "type": "poster",
  "territory_id": 5,
  "start_date": "2024-02-01",
  "end_date": "2024-03-01",
  "total_posters": 500
}
```

### 3. Generar QR Codes

```bash
POST /api/poster-qr/campaigns/1/generate-codes

{
  "quantity": 500,
  "base_url": "https://tucampana.com/qr-landing",
  "territory_id": 5,
  "poster_batch": "Lote-Centro-001"
}
```

**Respuesta**: 500 códigos QR únicos con URLs como:
- `https://tucampana.com/qr-landing?qr=QR-A1B2C3D4`
- `https://tucampana.com/qr-landing?qr=QR-E5F6G7H8`

### 4. Imprimir Afiches

Usa los códigos generados para crear QR en tus afiches. Cada QR apunta a la landing page con el código único.

---

## 📱 Landing Page

Ya está creado en `resources/views/qr-landing.blade.php`

**URL Pública**: `https://tucampana.com/qr-landing?qr=QR-ABC12345`

### Características:

✅ **Diseño responsive** (móvil/desktop)  
✅ **Captura ubicación GPS** automáticamente  
✅ **Formulario completo** con validaciones  
✅ **Consentimientos legales** (Ley 1581)  
✅ **Experiencia UX optimizada**  
✅ **Envío AJAX** sin recargar página  

### Datos que Captura:

**Personales**:
- Nombre completo (obligatorio)
- Email
- Teléfono
- Documento (tipo y número)
- Fecha nacimiento
- Género

**Ubicación**:
- Dirección
- Barrio
- Ciudad
- GPS (latitud/longitud)

**Intereses** (checkboxes):
- Seguridad
- Educación
- Salud
- Empleo
- Movilidad
- Medio Ambiente
- Vivienda
- Cultura/Deporte

**Apoyo**:
- Nivel de interés (muy interesado → poco interesado)
- ¿Quiere ser voluntario?
- ¿Quiere donar?
- ¿Quiere recibir updates?

**Consentimientos** (obligatorio):
- ✅ Autorización tratamiento datos (Ley 1581)
- Autorización de contacto

---

## 📊 Análisis y Reportes

### 1. Ver Todos los Leads

```bash
GET /api/qr-leads?campaign_id=1&support_level=muy_interesado

Respuesta:
{
  "data": [
    {
      "id": 1,
      "full_name": "María García",
      "email": "maria@example.com",
      "phone": "+573001234567",
      "territory": { "name": "Centro" },
      "support_level": "muy_interesado",
      "wants_volunteer": true,
      "interests": ["seguridad", "educacion"],
      "scanned_at": "2024-02-15 14:30:00",
      "converted_at": "2024-02-15 14:35:00"
    }
  ]
}
```

### 2. Análisis por Campaña

```bash
GET /api/qr-leads/campaign/1/analysis

Respuesta:
{
  "total_leads": 245,
  "converted_leads": 180,
  "conversion_rate": 73.47,
  
  "gender_distribution": {
    "male": 120,
    "female": 115,
    "other": 10
  },
  
  "avg_age": 34.5,
  
  "age_groups": {
    "18-25": 45,
    "26-35": 95,
    "36-50": 80,
    "51+": 25
  },
  
  "support_levels": {
    "muy_interesado": 120,
    "interesado": 90,
    "neutral": 30,
    "poco_interesado": 5
  },
  
  "top_interests": {
    "seguridad": 150,
    "educacion": 120,
    "empleo": 95,
    "salud": 80,
    "movilidad": 60
  },
  
  "wants_volunteer": 85,
  "wants_donate": 45,
  "wants_updates": 200,
  
  "by_territory": {
    "5": {
      "count": 120,
      "converted": 95,
      "muy_interesado": 75
    },
    "8": {
      "count": 125,
      "converted": 85,
      "muy_interesado": 45
    }
  }
}
```

### 3. Comparativa Territorial

```bash
GET /api/qr-leads/territorial-comparison?territories[]=5&territories[]=8&territories[]=12

Respuesta (ordenado por support_score):
[
  {
    "territory_id": 5,
    "territory_name": "Centro",
    "total_leads": 120,
    "conversion_rate": 79.17,
    "support_score": 3.65,  // Score 0-4 (muy_interesado=4, interesado=3, neutral=1)
    "top_interest": "seguridad",
    "wants_volunteer_percent": 45.8
  },
  {
    "territory_id": 12,
    "territory_name": "Norte",
    "total_leads": 95,
    "conversion_rate": 68.42,
    "support_score": 3.12,
    "top_interest": "educacion",
    "wants_volunteer_percent": 32.1
  },
  {
    "territory_id": 8,
    "territory_name": "Sur",
    "total_leads": 85,
    "conversion_rate": 55.29,
    "support_score": 2.85,
    "top_interest": "empleo",
    "wants_volunteer_percent": 28.2
  }
]
```

**Insights**:
- Centro tiene **mejor apoyo** (score 3.65)
- Centro tiene **mayor conversión** (79%)
- Norte se interesa más en **educación**
- Sur prioriza **empleo**

### 4. Exportar a CSV

```bash
GET /api/qr-leads/campaign/1/export

Descarga archivo CSV con todos los leads para análisis en Excel
```

---

## 👥 Seguimiento de Leads

### 1. Registrar Interacción

```bash
POST /api/qr-leads/1/interaction

{
  "type": "call",
  "subject": "Llamada de seguimiento",
  "description": "Se contactó a María, está muy interesada. Quiere asistir al próximo evento.",
  "result": "successful"
}
```

### 2. Registrar Conversión

```bash
POST /api/qr-leads/1/conversion

{
  "conversion_type": "volunteer",
  "conversion_value": "Voluntario confirmado para evento 15 de marzo"
}
```

Tipos de conversión:
- `volunteer` - Se hizo voluntario
- `donor` - Hizo donación
- `event_attendee` - Asistió a evento
- `voter_confirmed` - Confirmó su voto
- `social_share` - Compartió en redes

---

## 📈 Casos de Uso Reales

### Caso 1: Campaña de Afiches en 5 Barrios

```bash
# 1. Crear campaña
POST /api/poster-qr/campaigns
{
  "name": "Afiches 5 Barrios - Seguridad",
  "total_posters": 250
}

# 2. Generar 250 QR (50 por barrio)
POST /api/poster-qr/campaigns/1/generate-codes
{
  "quantity": 50,
  "territory_id": 5,  // Centro
  "base_url": "https://tucampana.com/qr-landing"
}

# Repetir para territorios 6, 7, 8, 9

# 3. Voluntarios colocan afiches
# Cada afiche tiene QR único

# 4. Después de 1 semana, analizar
GET /api/qr-leads/campaign/1/analysis

# RESULTADOS:
# - 180 personas escanearon
# - 120 dejaron datos (67% conversión)
# - 85 quieren ser voluntarios
# - Barrio Centro: mayor interés en seguridad
# - Barrio Sur: mayor interés en empleo
```

### Caso 2: Detectar Zonas Calientes

```bash
# Comparar 10 barrios
GET /api/qr-leads/territorial-comparison?territories[]=1,2,3,4,5,6,7,8,9,10

# INSIGHTS:
# - Barrios 3 y 5: support_score > 3.5 (MUY INTERESADOS)
# - Barrio 8: support_score < 2.0 (POCO INTERÉS)
# 
# ACCIÓN:
# - Reforzar presencia en barrios 3 y 5
# - Cambiar mensaje en barrio 8
# - Organizar evento en barrio 3
```

### Caso 3: Comparar con Competencia

**Tu campaña**:
- 250 afiches QR
- 120 leads capturados
- 85 quieren ser voluntarios (70.8%)
- Support score promedio: 3.4

**Competencia** (estimado de redes sociales):
- Engagement rate: 2.5%
- Sentiment score: 0.45
- Followers: 15,000

**TU VENTAJA**:
- ✅ Datos REALES de ciudadanos (no solo likes)
- ✅ Información demográfica precisa
- ✅ Contacto directo (email/teléfono)
- ✅ Mayor tasa de conversión a voluntarios

---

## 🎯 Estrategias Avanzadas

### 1. A/B Testing de Mensajes

Imprime 2 versiones de afiches (cada una con QR distintos):

**Versión A**: "¿Preocupado por la seguridad?"  
**Versión B**: "Juntos construimos seguridad"

Después de 1 semana:
- Versión A: 60 scans, 40 leads (67%)
- Versión B: 80 scans, 65 leads (81%)

**Conclusión**: Mensaje positivo (B) funciona mejor → usar en toda la campaña

### 2. Segmentación por Edad

```bash
GET /api/qr-leads?campaign_id=1

# Analizar en Excel:
# - 18-25 años: priorizan empleo
# - 26-40 años: priorizan educación
# - 41+ años: priorizan seguridad
#
# ACCIÓN:
# - Eventos de empleo para jóvenes
# - Propuestas de educación para familias
# - Foros de seguridad para adultos
```

### 3. Detección de Duplicados

El sistema detecta automáticamente si alguien escanea múltiples QR:

```php
$lead->is_duplicate; // true
$lead->duplicate_of; // ID del lead original
```

Útil para:
- No contar dos veces a la misma persona
- Identificar ciudadanos muy interesados (escanearon 3+ QR)

---

## 🔐 Cumplimiento Legal (Ley 1581)

✅ **Consentimiento obligatorio** antes de capturar datos  
✅ **IP y timestamp** del consentimiento guardados  
✅ **Política de privacidad** enlazada en formulario  
✅ **Opciones de contacto** separadas del consentimiento base  
✅ **Derecho a rectificar/eliminar** datos implementado  

### Crear Política de Privacidad

Debes tener en `/politica-privacidad`:

- Quién es el responsable de datos
- Para qué se usan los datos
- Cuánto tiempo se guardan
- Cómo ejercer derechos (ARCO)
- Datos de contacto DPO

---

## 📊 Dashboard Recomendado

Crear vista con:

1. **Mapa de calor**
   - Scans por barrio
   - Color según support_score

2. **Métricas principales**
   - Total leads
   - Tasa conversión
   - Quieren voluntarios

3. **Gráficas**
   - Leads por día
   - Distribución etaria
   - Top intereses

4. **Top 10 Leads**
   - Muy interesados + quieren voluntario
   - Para seguimiento prioritario

---

## 🚀 Próximos Pasos

1. ✅ Ejecutar migraciones
2. ✅ Crear campaña de afiches
3. ✅ Generar QR codes
4. ✅ Imprimir afiches
5. ✅ Colocar en territorios
6. ✅ Monitorear scans diariamente
7. ✅ Hacer seguimiento a leads
8. ✅ Convertir en voluntarios/donantes
9. ✅ Analizar y ajustar estrategia
10. ✅ Repetir en nuevos territorios

---

## 🎉 Resultado Esperado

Después de 1 mes con 500 afiches QR:

- **300-400 scans** (60-80%)
- **200-300 leads capturados** (conversión 67-75%)
- **100-150 muy interesados** (33-50%)
- **50-80 voluntarios** (17-27%)
- **20-30 donantes** (7-10%)

**Datos valiosos**:
- Mapa completo de apoyo por territorio
- Demografía de tu base
- Temas que más importan
- Base de datos para GOTV (Get Out The Vote)

---

**¡Sistema completo listo para usar!** 🎯

Ahora puedes trackear cada QR, capturar datos, analizar por territorio y comparar con competencia usando datos reales.