social-media-automation/docs/ANALYTICS.md

# Analytics y Reportes

Sistema completo de métricas y análisis de rendimiento para optimizar tu estrategia de contenido.

## Modelos de Datos

### PostMetrics
Registra métricas de cada post a lo largo del tiempo.

```python
PostMetrics:
    id: int
    post_id: int (FK -> posts)
    platform: str  # x, threads, instagram, facebook
    likes: int
    comments: int
    shares: int
    impressions: int
    reach: int
    saves: int
    clicks: int
    replies: int
    quotes: int
    engagement_rate: float
    recorded_at: datetime
```

### AnalyticsReport
Reportes agregados (diarios, semanales, mensuales).

```python
AnalyticsReport:
    id: int
    report_type: str  # daily, weekly, monthly
    period_start: date
    period_end: date
    platform: str (opcional)
    total_posts: int
    total_impressions: int
    total_engagements: int
    avg_engagement_rate: float
    top_posts: JSON  # Lista de mejores posts
    best_times: JSON  # Mejores horarios
    content_performance: JSON  # Por tipo de contenido
    platform_breakdown: JSON  # Por plataforma
    summary_text: str  # Texto para Telegram
```

## API Endpoints

### GET /api/analytics/dashboard
Obtiene datos del dashboard principal.

**Parámetros:**
- `days` (int, default=30): Período a analizar
- `platform` (str, opcional): Filtrar por plataforma

**Respuesta:**
```json
{
    "period_days": 30,
    "total_posts": 45,
    "total_impressions": 125000,
    "total_engagements": 3500,
    "total_likes": 2800,
    "total_comments": 450,
    "total_shares": 250,
    "avg_engagement_rate": 2.8,
    "platform_breakdown": {
        "x": {"posts": 20, "engagements": 1500},
        "threads": {"posts": 25, "engagements": 2000}
    },
    "content_breakdown": {
        "tip_tech": {"posts": 15, "engagements": 1200},
        "producto": {"posts": 10, "engagements": 800}
    },
    "pending_interactions": 12
}
```

### GET /api/analytics/top-posts
Obtiene los posts con mejor rendimiento.

**Parámetros:**
- `days` (int, default=30): Período a analizar
- `limit` (int, default=10): Máximo de posts
- `platform` (str, opcional): Filtrar por plataforma

**Respuesta:**
```json
{
    "posts": [
        {
            "id": 123,
            "content": "Tip: Usa IA para...",
            "content_type": "tip_tech",
            "platforms": ["x", "threads"],
            "published_at": "2025-01-15T10:00:00",
            "likes": 150,
            "comments": 25,
            "shares": 30,
            "impressions": 5000,
            "engagement_rate": 4.1
        }
    ],
    "count": 10
}
```

### GET /api/analytics/optimal-times
Calcula los mejores horarios para publicar basado en datos históricos.

**Parámetros:**
- `platform` (str, opcional): Filtrar por plataforma
- `days` (int, default=90): Días de datos a analizar

**Respuesta:**
```json
{
    "optimal_times": [
        {
            "day": 1,
            "day_name": "Mar",
            "hour": 12,
            "hour_formatted": "12:00",
            "avg_engagement_rate": 4.5,
            "sample_size": 15
        }
    ],
    "analysis_period_days": 90,
    "platform": "x"
}
```

### GET /api/analytics/engagement-trend
Obtiene tendencia de engagement para gráficos.

**Parámetros:**
- `days` (int, default=30): Período
- `platform` (str, opcional): Plataforma

**Respuesta:**
```json
{
    "trend": [
        {
            "date": "2025-01-01",
            "posts": 3,
            "impressions": 5000,
            "engagements": 200
        }
    ],
    "period_days": 30,
    "platform": null
}
```

### GET /api/analytics/reports
Obtiene reportes históricos.

**Parámetros:**
- `report_type` (str): daily, weekly, monthly
- `limit` (int, default=10): Máximo de reportes

### POST /api/analytics/reports/generate
Genera un nuevo reporte.

**Parámetros:**
- `report_type` (str): weekly (otros tipos próximamente)

### POST /api/analytics/reports/send-telegram
Genera y envía reporte por Telegram.

### GET /api/analytics/posts/{post_id}/metrics
Obtiene métricas detalladas de un post específico.

**Respuesta:**
```json
{
    "post_id": 123,
    "current_metrics": {"likes": 150, "comments": 25},
    "published_at": "2025-01-15T10:00:00",
    "platforms": ["x", "threads"],
    "metrics_history": [
        {
            "recorded_at": "2025-01-15T12:00:00",
            "likes": 50,
            "comments": 10,
            "engagement_rate": 2.5
        }
    ]
}
```

## Tareas Programadas

### fetch_post_metrics
- **Frecuencia:** Cada 15 minutos
- **Función:** Obtiene métricas actualizadas de las APIs de cada plataforma
- **Posts afectados:** Publicados en los últimos 7 días

### generate_weekly_analytics_report
- **Frecuencia:** Domingos a las 9:00 AM
- **Función:** Genera reporte semanal completo
- **Acciones:**
  - Calcula métricas agregadas
  - Compara con semana anterior
  - Genera texto para Telegram
  - Envía notificación (si está configurado)

### recalculate_optimal_times
- **Frecuencia:** Lunes a las 2:00 AM
- **Función:** Recalcula mejores horarios basado en últimos 90 días

## Dashboard

Accede al dashboard de analytics en `/dashboard/analytics`.

### Características:
- **Cards de métricas:** Posts, impresiones, engagements, tasa
- **Gráfico de tendencia:** Chart.js con impresiones y engagements
- **Desglose por plataforma:** Comparativa visual
- **Top posts:** Lista de mejores performers
- **Mejores horarios:** Mapa de calor visual
- **Rendimiento por contenido:** Por tipo de publicación

## Configuración

```bash
# .env
ANALYTICS_FETCH_INTERVAL=15  # minutos
TELEGRAM_REPORT_ENABLED=true
TELEGRAM_REPORT_DAY=6  # 0=Lunes, 6=Domingo
```

## Ejemplo de Uso

```python
from app.services.analytics_service import analytics_service

# Obtener stats del dashboard
stats = await analytics_service.get_dashboard_stats(days=30, platform="x")

# Obtener top posts
top = await analytics_service.get_top_posts(days=7, limit=5)

# Generar reporte semanal
report = await analytics_service.generate_weekly_report()
print(report.summary_text)  # Texto formateado para Telegram
```

## Cálculos

### Engagement Rate
```
engagement_rate = (likes + comments + shares) / impressions * 100
```

### Score de Horario Óptimo
```
Para cada combinación (día, hora):
  promedio_engagement = sum(engagement_rates) / count(posts)
  ordenar por promedio_engagement descendente
```