# 📊 Dashboard Avançado para Merchants e Admin

## Visão Geral

O Dashboard Avançado fornece uma visão completa e detalhada de todas as métricas, estatísticas e análises de campanhas para merchants e administradores. Inclui métricas quantitativas e qualitativas, comparações entre campanhas, análises temporais e insights inteligentes.

---

## 🔗 Endpoints Disponíveis

### 1. Dashboard Principal Completo
**GET** `/api/merchant-dashboard`

Retorna todas as informações do dashboard em uma única chamada.

#### Query Parameters:
- `period` (opcional): `7d` | `30d` | `90d` | `1y` (padrão: `30d`)
- `establishment_id` (opcional): ID do estabelecimento para filtrar (apenas para merchant)
- `compare_period` (opcional): `true` | `false` - Comparar com período anterior (padrão: `false`)

#### Resposta:
```json
{
  "success": true,
  "data": {
    "period": {
      "type": "30d",
      "days": 30,
      "start_date": "2024-10-03T00:00:00.000Z",
      "end_date": "2024-11-02T00:00:00.000Z",
      "previous_period": null
    },
    "user": {
      "user_id": 2,
      "role": "merchant",
      "accessible_establishments": [...],
      "target_establishment_id": null
    },
    "quantitative_metrics": {
      "total_campaigns": 15,
      "active_campaigns": 8,
      "inactive_campaigns": 5,
      "cancelled_campaigns": 2,
      "total_purchases": 120,
      "confirmed_purchases": 100,
      "unique_customers": 45,
      "total_revenue": 50000.00,
      "avg_purchase_amount": 500.00,
      "total_points_given": 5000,
      "conversion_rate": 83.33,
      "points_per_real": 0.10,
      "by_campaign_type": [...]
    },
    "qualitative_metrics": {
      "roi": {
        "value": 150.50,
        "revenue": 50000.00,
        "total_investment": 20000.00,
        "points_invested": 5000,
        "communication_budget": 15000.00
      },
      "engagement": {
        "score": 75.50,
        "rate": 2.5,
        "engaged_users": 45,
        "total_interactions": 120
      },
      "effectiveness": {
        "rate": 80.00,
        "successful_campaigns": 12,
        "total_campaigns": 15
      },
      "performance_score": 85.25
    },
    "campaign_comparisons": {
      "campaigns": [...],
      "benchmarks": {
        "average_revenue": 3333.33,
        "average_purchases": 8.0,
        "total_campaigns": 15,
        "top_performers": 5,
        "below_average": 3
      }
    },
    "temporal_analysis": {
      "timeline": [...],
      "trends": {
        "revenue": "growing",
        "purchases": "growing",
        "revenue_growth": 25.5,
        "purchase_growth": 15.2
      }
    },
    "previous_period_comparison": null,
    "rankings": {
      "top_campaigns_by_revenue": [...],
      "top_campaigns_by_engagement": [...],
      "top_establishments": [...]
    },
    "insights": {
      "insights": [...],
      "recommendations": [...],
      "warnings": [...],
      "summary": {
        "total_insights": 3,
        "total_recommendations": 2,
        "total_warnings": 1,
        "overall_sentiment": "positive"
      }
    },
    "summary": {
      "total_campaigns": 15,
      "active_campaigns": 8,
      "total_revenue": 50000.00,
      "total_points_given": 5000,
      "average_roi": 150.50,
      "engagement_score": 75.50,
      "performance_score": 85.25
    }
  }
}
```

### 2. Métricas Específicas
**GET** `/api/merchant-dashboard/metrics`

Retorna métricas específicas (quantitativas ou qualitativas).

#### Query Parameters:
- `type` (opcional): `all` | `quantitative` | `qualitative` (padrão: `all`)
- `period` (opcional): `7d` | `30d` | `90d` | `1y` (padrão: `30d`)
- `establishment_id` (opcional): ID do estabelecimento para filtrar

---

## 📊 Métricas Quantitativas

### KPIs Principais:
- **Total de Campanhas**: Número total de campanhas criadas
- **Campanhas Ativas**: Campanhas com status "Activo"
- **Campanhas Inativas**: Campanhas com status "Parado"
- **Campanhas Canceladas**: Campanhas canceladas
- **Campanhas Expiradas**: Campanhas que passaram da data de validade
- **Campanhas Agendadas**: Campanhas que ainda não começaram

### Métricas de Compras:
- **Total de Compras**: Número total de compras
- **Compras Confirmadas**: Compras com status "confirmed"
- **Compras Pendentes**: Compras aguardando confirmação
- **Compras Rejeitadas**: Compras rejeitadas
- **Clientes Únicos**: Número de clientes distintos

### Métricas de Receita:
- **Receita Total**: Soma de todas as compras confirmadas
- **Valor Médio de Compra**: Média do valor das compras
- **Maior Compra**: Valor da maior compra
- **Menor Compra**: Valor da menor compra

### Métricas de Pontos:
- **Total de Pontos Dados**: Soma de todos os pontos concedidos
- **Média de Pontos por Compra**: Média de pontos por transação
- **Pontos por Real**: Eficiência (pontos dados / receita)

### Taxas e Eficiência:
- **Taxa de Conversão**: (Compras Confirmadas / Total de Compras) * 100
- **Pontos por Real**: Total de pontos / Receita total

---

## 🎯 Métricas Qualitativas

### ROI (Return on Investment):
- **Valor do ROI**: ((Receita - Investimento) / Investimento) * 100
- **Receita Total**: Soma de todas as receitas
- **Investimento Total**: Pontos investidos + Orçamento de comunicação
- **Valor dos Pontos**: Pontos investidos * 0.01 MT (ajustável)

### Engajamento:
- **Score de Engajamento**: (Usuários Engajados / Total de Campanhas) * 10
- **Taxa de Engajamento**: Total de interações / Total de campanhas
- **Usuários Engajados**: Número de usuários únicos que interagiram
- **Total de Interações**: Número total de interações (compras)

### Eficácia:
- **Taxa de Eficácia**: (Campanhas Bem-sucedidas / Total de Campanhas) * 100
- **Campanhas Bem-sucedidas**: Campanhas com pelo menos uma compra confirmada
- **Média de Usuários por Campanha**: Média de usuários únicos por campanha

### Score de Performance:
- **Score Geral (0-100)**: Combinação ponderada de:
  - ROI: 40%
  - Engajamento: 30%
  - Eficácia: 30%

---

## 🔄 Comparações entre Campanhas

### Para Merchants:
- Compara campanhas **do mesmo estabelecimento**
- Identifica top performers
- Identifica campanhas abaixo da média
- Calcula benchmarks (média de receita, média de compras)

### Para Admin:
- Compara campanhas de **diferentes estabelecimentos**
- Rankings globais
- Top estabelecimentos
- Análise cross-establishment

### Classificação de Campanhas:
- **Top Performer**: Receita > 120% da média E Compras > 120% da média
- **Average**: Dentro da faixa normal
- **Below Average**: Receita < 80% da média OU Compras < 80% da média

### Métricas Comparativas:
- **Diferença de Receita**: Receita da campanha - Média de receita
- **Diferença Percentual de Receita**: ((Receita - Média) / Média) * 100
- **Diferença de Compras**: Compras da campanha - Média de compras
- **Diferença Percentual de Compras**: ((Compras - Média) / Média) * 100

---

## 📈 Análise Temporal

### Timeline:
- Agrupamento por período:
  - **Diário**: Para períodos <= 30 dias
  - **Semanal**: Para períodos > 30 e <= 90 dias
  - **Mensal**: Para períodos > 90 dias

### Métricas por Período:
- Número de compras
- Clientes únicos
- Receita
- Pontos dados
- Campanhas ativas

### Tendências:
- **Crescimento**: Receita/compras aumentaram > 10% na segunda metade do período
- **Declínio**: Receita/compras diminuíram > 10% na segunda metade do período
- **Estável**: Variação dentro de ±10%

### Crescimento:
- **Crescimento de Receita**: ((Receita Final - Receita Inicial) / Receita Inicial) * 100
- **Crescimento de Compras**: ((Compras Finais - Compras Iniciais) / Compras Iniciais) * 100

---

## 📊 Rankings

### Top Campanhas por Receita:
- Top 10 campanhas com maior receita
- Inclui: ID, nome, tipo, estabelecimento, receita

### Top Campanhas por Engajamento:
- Top 10 campanhas com mais clientes únicos
- Inclui: ID, nome, tipo, estabelecimento, clientes únicos

### Top Estabelecimentos (apenas Admin):
- Top 10 estabelecimentos por receita
- Inclui: ID, nome, número de campanhas, número de compras, receita

---

## 💡 Insights e Recomendações

### Insights Positivos:
- ROI excelente (> 100%)
- Receita em crescimento
- Top performers identificados
- Aumento significativo em relação ao período anterior

### Recomendações:
- Melhorar engajamento (score < 30)
- Revisar estratégias de campanha
- Ajustar taxas de conversão

### Avisos:
- **Crítico**: ROI negativo, receita em declínio significativo
- **Alto**: Taxa de conversão baixa, custo de pontos alto
- **Médio**: Mais campanhas abaixo da média, receita em declínio

### Sentimento Geral:
- **Positive**: Mais insights positivos que avisos
- **Negative**: Mais avisos que insights positivos
- **Neutral**: Equilíbrio entre insights e avisos

---

## 🔐 Permissões

### Merchants:
- Acesso apenas às campanhas dos seus estabelecimentos
- Comparações limitadas ao mesmo estabelecimento
- Não vê rankings de outros estabelecimentos

### Admin:
- Acesso a todas as campanhas
- Comparações cross-establishment
- Rankings globais
- Top estabelecimentos

---

## 📝 Exemplos de Uso

### 1. Dashboard Completo (Merchant)
```bash
GET /api/merchant-dashboard?period=30d&establishment_id=123
```

### 2. Dashboard com Comparação de Período
```bash
GET /api/merchant-dashboard?period=30d&compare_period=true
```

### 3. Métricas Quantitativas Apenas
```bash
GET /api/merchant-dashboard/metrics?type=quantitative&period=90d
```

### 4. Métricas Qualitativas Apenas
```bash
GET /api/merchant-dashboard/metrics?type=qualitative&period=30d
```

### 5. Dashboard Admin (Todos os Estabelecimentos)
```bash
GET /api/merchant-dashboard?period=90d
```

---

## 🎨 Visualizações Recomendadas

### Gráficos Sugeridos:
1. **Gráfico de Linha**: Timeline de receita e compras
2. **Gráfico de Barras**: Comparação entre campanhas
3. **Gráfico de Pizza**: Distribuição por tipo de campanha
4. **Gráfico de Área**: Crescimento ao longo do tempo
5. **Tabela**: Rankings de campanhas
6. **Cards de KPI**: Métricas principais
7. **Gauge**: Score de performance
8. **Heatmap**: Engajamento por período

---

## ⚠️ Notas Importantes

1. **Períodos**: Use períodos apropriados para análise:
   - `7d`: Análise semanal rápida
   - `30d`: Análise mensal padrão
   - `90d`: Análise trimestral
   - `1y`: Análise anual

2. **Comparação de Período**: Ative apenas quando necessário, pois aumenta o tempo de processamento

3. **Filtro por Estabelecimento**: Merchants podem filtrar por estabelecimento específico

4. **Performance**: Para grandes volumes de dados, considere usar períodos menores ou filtrar por estabelecimento

5. **Cache**: Considere implementar cache para dashboards frequentes

---

## 🔄 Atualizações Futuras

- [ ] Exportação de relatórios (PDF, Excel)
- [ ] Agendamento de relatórios
- [ ] Alertas automáticos baseados em métricas
- [ ] Previsões e projeções
- [ ] Análise de coorte
- [ ] Segmentação de clientes
- [ ] A/B testing insights