# 📊 Dashboard API - Documentação Completa

## Visão Geral

O Dashboard Avançado fornece uma visão completa e detalhada de todas as atividades, métricas e estatísticas do usuário logado no sistema de pontos Maktubia.

---

## 🔗 Endpoints Disponíveis

### 1. Dashboard Principal (Completo)
**GET** `/api/dashboard`

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

#### Query Parameters:
- `period` (opcional): `7d` | `30d` | `90d` (padrão: `30d`)
- `type` (opcional): `all` | `points` | `purchases` | `transfers` | `friends` (padrão: `all`)

#### 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"
    },
    "user": {
      "user_id": 2,
      "wallet": {
        "points": 700,
        "balance": 1000.00,
        "updated_at": "2024-11-02T14:31:54.832Z"
      },
      "activity": {
        "purchases_count": 5,
        "transfers_count": 3,
        "friends_count": 8
      }
    },
    "points": {
      "current_balance": 700,
      "pending": 300,
      "total_available": 1000,
      "balance": 1000.00,
      "period": {
        "earned": 500,
        "spent": 100,
        "net": 400,
        "transactions": 15
      }
    },
    "purchases": {
      "total_count": 10,
      "confirmed_count": 8,
      "pending_count": 2,
      "rejected_count": 0,
      "total_amount": 5000.00,
      "confirmed_amount": 4000.00,
      "total_points_earned": 1000,
      "confirmed_points_earned": 800,
      "pending_points": 200,
      "avg_amount": 500.00,
      "max_amount": 2000.00,
      "min_amount": 100.00,
      "top_establishments": [
        {
          "establishment_id": "EST_001",
          "name": "Loja Central",
          "visits": 5,
          "total_spent": 2500.00,
          "total_points": 500
        }
      ]
    },
    "transfers": {
      "total_count": 15,
      "sent_count": 8,
      "received_count": 7,
      "points_sent": 500,
      "points_received": 600,
      "net_points": 100,
      "avg_amount": 70,
      "max_amount": 200,
      "top_friends": [
        {
          "friend_id": 3,
          "name": "Maria Santos",
          "user_code": "MK000003",
          "transfer_count": 5,
          "total_amount": 300
        }
      ]
    },
    "friends": {
      "total": 8,
      "new_in_period": 2,
      "pending_requests": 1,
      "most_active": [
        {
          "friend_id": 3,
          "name": "Maria Santos",
          "user_code": "MK000003",
          "interaction_count": 5,
          "total_interaction_amount": 300
        }
      ]
    },
    "establishments": {
      "visited_count": 5,
      "favorites": [
        {
          "establishment_id": "EST_001",
          "name": "Loja Central",
          "type": "Loja",
          "visit_count": 5,
          "total_spent": 2500.00,
          "total_points_earned": 500
        }
      ]
    },
    "charts": {
      "points_timeline": [
        {
          "date": "2024-11-01",
          "earned": 50,
          "spent": 10,
          "net": 40
        }
      ],
      "purchases_timeline": [
        {
          "date": "2024-11-01",
          "count": 2,
          "amount": 500.00,
          "points": 100
        }
      ],
      "purchases_by_status": [
        {
          "status": "confirmed",
          "count": 8,
          "amount": 4000.00
        }
      ],
      "transfers_distribution": [
        {
          "type": "sent",
          "count": 8,
          "total_points": 500
        }
      ],
      "purchases_by_establishment": [
        {
          "establishment_id": "EST_001",
          "name": "Loja Central",
          "count": 5,
          "amount": 2500.00
        }
      ]
    },
    "activities": [
      {
        "type": "purchase",
        "id": "COMPRA_001",
        "code": "COMPRA_001",
        "title": "Compra de 500.00 MZN",
        "description": "Loja Central",
        "amount": 500.00,
        "points": 100,
        "status": "confirmed",
        "created_at": "2024-11-02T14:31:54.832Z"
      }
    ],
    "trends": {
      "purchases": {
        "trend": "up",
        "percentage": 25.5,
        "current": 10,
        "previous": 8
      },
      "amount": {
        "trend": "up",
        "percentage": 15.3,
        "current": 5000.00,
        "previous": 4335.00
      },
      "points": {
        "trend": "up",
        "percentage": 20.0,
        "current": 1000,
        "previous": 833
      },
      "projection": {
        "avg_points_per_day": 33,
        "projected_points_30_days": 990,
        "days_analyzed": 30
      },
      "insights": [
        {
          "type": "positive",
          "title": "Aumento de Compras",
          "message": "Suas compras aumentaram 25.5% em relação ao período anterior!"
        }
      ]
    },
    "summary": {
      "total_points": 700,
      "total_purchases": 10,
      "total_transfers": 15,
      "total_friends": 8,
      "total_establishments": 5,
      "pending_points": 300,
      "activity_score": 75
    }
  },
  "message": "Dashboard carregado com sucesso"
}
```

---

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

Retorna métricas específicas do dashboard.

#### Query Parameters:
- `type` (obrigatório): `points` | `purchases` | `transfers` | `friends`
- `period` (opcional): `7d` | `30d` | `90d` (padrão: `30d`)

#### Exemplo:
```
GET /api/dashboard/metrics?type=points&period=30d
```

---

### 3. Dados para Gráficos
**GET** `/api/dashboard/charts`

Retorna dados formatados para exibição em gráficos.

#### Query Parameters:
- `type` (opcional): `timeline` | `distribution` | `all` (padrão: `all`)
- `period` (opcional): `7d` | `30d` | `90d` (padrão: `30d`)

#### Exemplo:
```
GET /api/dashboard/charts?type=timeline&period=7d
```

---

### 4. Atividades Recentes
**GET** `/api/dashboard/activities`

Retorna atividades recentes do usuário (compras, transferências, pontos).

#### Query Parameters:
- `limit` (opcional): Número de atividades (padrão: 20)

#### Exemplo:
```
GET /api/dashboard/activities?limit=10
```

---

## 📈 Funcionalidades

### 1. Estatísticas Completas
- ✅ Informações do usuário e wallet
- ✅ Estatísticas de pontos (ganhos, gastos, pendentes)
- ✅ Estatísticas de compras (total, confirmadas, pendentes)
- ✅ Estatísticas de transferências (enviadas/recebidas)
- ✅ Estatísticas de amigos
- ✅ Estatísticas de estabelecimentos visitados

### 2. Dados para Gráficos
- ✅ Timeline de pontos (diário)
- ✅ Timeline de compras (diário)
- ✅ Distribuição de compras por status
- ✅ Distribuição de transferências (enviadas vs recebidas)
- ✅ Distribuição de compras por estabelecimento

### 3. Atividades Recentes
- ✅ Últimas compras
- ✅ Últimas transferências
- ✅ Últimas transações de pontos
- ✅ Ordenadas por data (mais recente primeiro)

### 4. Tendências e Insights
- ✅ Comparação com período anterior
- ✅ Percentual de mudança
- ✅ Projeções futuras
- ✅ Insights automáticos

### 5. Top Rankings
- ✅ Top estabelecimentos visitados
- ✅ Top amigos (por transferências)
- ✅ Amigos mais ativos

---

## 🎯 Casos de Uso

### 1. Dashboard Principal do App
```
GET /api/dashboard?period=30d
```
Mostra visão geral completa dos últimos 30 dias.

### 2. Gráfico de Pontos ao Longo do Tempo
```
GET /api/dashboard/charts?type=timeline&period=7d
```
Dados para gráfico de linha mostrando evolução de pontos.

### 3. Distribuição de Compras
```
GET /api/dashboard/charts?type=distribution&period=30d
```
Dados para gráfico de pizza/barras mostrando distribuição.

### 4. Atividades Recentes (Feed)
```
GET /api/dashboard/activities?limit=20
```
Lista de atividades recentes para feed do usuário.

### 5. Métricas Específicas
```
GET /api/dashboard/metrics?type=purchases&period=90d
```
Métricas detalhadas de compras dos últimos 90 dias.

---

## 🔒 Autenticação

Todas as rotas requerem autenticação via JWT token:

```
Authorization: Bearer {token}
```

---

## 📝 Notas

- Todas as datas são em formato ISO 8601
- Valores monetários são em MZN (Metical)
- Pontos são sempre inteiros
- Períodos são calculados em dias corridos
- Tendências comparam período atual com período anterior de mesma duração

---

## 🚀 Performance

- Queries otimizadas com índices
- Cache recomendado para dados que não mudam frequentemente
- Paginação disponível onde aplicável
- Limites de dados configuráveis (top 5, 10, etc.)

---

## ✅ Validações

- Usuário deve estar autenticado
- Período deve ser válido (7d, 30d, 90d)
- Tipo deve ser válido
- Limites são validados e limitados a máximo razoável