# 📊 Métricas Avançadas de Compras

## 📋 Resumo

Implementado sistema completo de métricas avançadas para todas as queries de compras, incluindo pontos ganhos, pontos gastos, transferências, recompensas e outras métricas úteis.

---

## 🎯 Endpoints com Métricas

### 1. **GET /api/purchases/my-purchases** (Minhas Compras)

Retorna lista de compras do usuário autenticado **com métricas completas**.

**Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "purchase_id": 1,
      "purchase_code": "COMPRA_1234567890_ABC123",
      "establishment_name": "Restaurante Sabor",
      "purchase_amount": 100.50,
      "points_earned": 20,
      "status": "confirmed"
    }
  ],
  "pagination": { ... },
  "metrics": {
    "purchases": {
      "total": 25,
      "confirmed": 20,
      "pending": 3,
      "rejected": 2,
      "cancelled": 0
    },
    "spending": {
      "totalSpent": 2500.50,
      "totalSpentConfirmed": 2000.50,
      "avgPurchaseAmount": 100.02,
      "maxPurchaseAmount": 500.00,
      "minPurchaseAmount": 25.00
    },
    "points": {
      "totalEarned": 400,
      "totalPotential": 500,
      "totalSpent": 150,
      "netPoints": 250,
      "currentPoints": 250,
      "currentBalance": 0,
      "avgPointsPerPurchase": 20,
      "pendingPoints": 100
    },
    "pointsSpent": {
      "total_points_spent": 100,
      "total_spent_transactions": 5,
      "avg_points_per_spent": 20,
      "last_points_spent_date": "2024-01-15T10:30:00Z"
    },
    "transfers": {
      "transfers_sent": 2,
      "transfers_received": 3,
      "points_sent": 30,
      "points_received": 50
    },
    "rewards": {
      "rewards_redeemed": 5,
      "points_spent_on_rewards": 20
    },
    "establishments": {
      "uniqueVisited": 8
    },
    "dates": {
      "firstPurchase": "2024-01-01T10:00:00Z",
      "lastPurchase": "2024-01-15T10:30:00Z",
      "firstConfirmedPurchase": "2024-01-01T10:00:00Z",
      "lastConfirmedPurchase": "2024-01-15T10:30:00Z",
      "daysSinceFirstPurchase": 14,
      "daysSinceLastPurchase": 0
    },
    "conversion": {
      "avgConversionRate": 20.0
    }
  }
}
```

---

### 2. **GET /api/purchases/:id** (Detalhes da Compra)

Retorna detalhes de uma compra específica **com métricas completas do usuário** (se a compra pertencer ao usuário).

**Resposta:**
```json
{
  "success": true,
  "data": {
    "purchase_id": 1,
    "purchase_amount": 100.50,
    "points_earned": 20,
    "status": "confirmed"
  },
  "metrics": {
    // Mesmas métricas de /my-purchases
  }
}
```

---

### 3. **GET /api/purchases** (Todas as Compras - Admin)

Retorna lista de todas as compras **com métricas agregadas** baseadas nos filtros aplicados.

**Resposta:**
```json
{
  "success": true,
  "data": [ ... ],
  "pagination": { ... },
  "meta": {
    "filters": {
      "status": "confirmed",
      "establishment_id": 5,
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  },
  "metrics": {
    "purchases": {
      "total": 100,
      "confirmed": 85,
      "pending": 10,
      "rejected": 5
    },
    "revenue": {
      "total": 10000.00,
      "confirmed": 8500.00,
      "avgPurchaseAmount": 100.00,
      "maxPurchaseAmount": 500.00,
      "minPurchaseAmount": 25.00
    },
    "points": {
      "totalGiven": 2000,
      "totalConfirmed": 1700,
      "avgPointsPerPurchase": 20
    },
    "customers": {
      "unique": 45
    },
    "establishments": {
      "unique": 12
    }
  }
}
```

---

## 📊 Métricas Disponíveis

### 🛒 **Métricas de Compras**

- `total` - Total de compras
- `confirmed` - Compras confirmadas (pontos já dados)
- `pending` - Compras pendentes (aguardando aprovação)
- `rejected` - Compras rejeitadas
- `cancelled` - Compras canceladas

### 💰 **Métricas de Gastos (Spending)**

- `totalSpent` - Total gasto em todas as compras
- `totalSpentConfirmed` - Total gasto em compras confirmadas
- `avgPurchaseAmount` - Valor médio por compra
- `maxPurchaseAmount` - Maior valor de compra
- `minPurchaseAmount` - Menor valor de compra

### 🎁 **Métricas de Pontos**

- `totalEarned` - Total de pontos ganhos (compras confirmadas)
- `totalPotential` - Total de pontos potenciais (todas as compras)
- `totalSpent` - Total de pontos gastos/usados
- `netPoints` - Pontos líquidos (ganhos - gastos)
- `currentPoints` - Pontos atuais na carteira
- `currentBalance` - Saldo atual
- `avgPointsPerPurchase` - Média de pontos por compra confirmada
- `pendingPoints` - Pontos pendentes (aguardando aprovação)

### 💸 **Métricas de Pontos Gastos (Points Spent)**

- `total_points_spent` - Total de pontos gastos
- `total_spent_transactions` - Número de transações de gasto
- `avg_points_per_spent` - Média de pontos por transação de gasto
- `last_points_spent_date` - Data da última transação de gasto

### 🔄 **Métricas de Transferências**

- `transfers_sent` - Número de transferências enviadas
- `transfers_received` - Número de transferências recebidas
- `points_sent` - Total de pontos enviados
- `points_received` - Total de pontos recebidos

### 🎁 **Métricas de Recompensas**

- `rewards_redeemed` - Número de recompensas resgatadas
- `points_spent_on_rewards` - Total de pontos gastos em recompensas

### 🏪 **Métricas de Estabelecimentos**

- `uniqueVisited` - Número de estabelecimentos únicos visitados

### 📅 **Métricas de Datas**

- `firstPurchase` - Data da primeira compra
- `lastPurchase` - Data da última compra
- `firstConfirmedPurchase` - Data da primeira compra confirmada
- `lastConfirmedPurchase` - Data da última compra confirmada
- `daysSinceFirstPurchase` - Dias desde a primeira compra
- `daysSinceLastPurchase` - Dias desde a última compra confirmada

### 📈 **Métricas de Conversão**

- `avgConversionRate` - Taxa de conversão média (% de pontos sobre valor gasto)

---

## 🔍 Métricas Calculadas

### **Para Usuários (GET /api/purchases/my-purchases e GET /api/purchases/:id)**

As métricas são calculadas considerando:
- ✅ Todas as compras do usuário
- ✅ Histórico de pontos (`points_history`)
- ✅ Transferências (`transfers`)
- ✅ Recompensas resgatadas (`reward_redemptions`)
- ✅ Carteira atual (`wallets`)

### **Para Administradores (GET /api/purchases)**

As métricas são calculadas considerando:
- ✅ Filtros aplicados (status, estabelecimento, usuário, data, valor)
- ✅ Agregações sobre todas as compras que atendem aos filtros
- ✅ Métricas de clientes únicos
- ✅ Métricas de estabelecimentos únicos

---

## ⚙️ Implementação Técnica

### Arquivos Modificados:

1. **`models/PurchasesModel.js`**
   - ✅ Novo método `getUserPurchaseMetrics(userId)` - Calcula métricas completas do usuário

2. **`controllers/purchaseController.js`**
   - ✅ `getMyPurchases` - Inclui métricas do usuário
   - ✅ `getPurchase` - Inclui métricas se a compra pertencer ao usuário
   - ✅ `getAllPurchases` - Inclui métricas agregadas baseadas nos filtros

### Características:

- ✅ **Performance**: Métricas calculadas em queries eficientes
- ✅ **Resiliente**: Se métricas falharem, a resposta ainda retorna dados
- ✅ **Dinâmico**: Detecta presença de tabelas (points_history, transfers, rewards)
- ✅ **Preciso**: Calcula pontos ganhos vs gastos vs atuais

---

## 📊 Exemplo de Uso

### Ver Minhas Compras com Métricas

```bash
GET /api/purchases/my-purchases?page=1&limit=10
Authorization: Bearer {token_cliente}
```

**Resposta incluirá:**
- Lista de compras
- Paginação
- **Métricas completas** do usuário

### Ver Compra Específica com Métricas

```bash
GET /api/purchases/123
Authorization: Bearer {token_cliente}
```

**Se a compra pertencer ao usuário, incluirá:**
- Detalhes da compra
- **Métricas completas** do usuário

### Ver Todas as Compras com Métricas Agregadas (Admin)

```bash
GET /api/purchases?status=confirmed&establishment_id=5&start_date=2024-01-01
Authorization: Bearer {token_admin}
```

**Resposta incluirá:**
- Lista de compras (com filtros)
- Paginação
- **Métricas agregadas** baseadas nos filtros aplicados

---

## ✅ Benefícios

1. ✅ **Visibilidade Completa**: Cliente vê todos os seus dados de compras e pontos
2. ✅ **Análise Avançada**: Métricas úteis para tomada de decisão
3. ✅ **Dashboard Ready**: Dados prontos para exibição em dashboards
4. ✅ **Performance**: Queries otimizadas e eficientes
5. ✅ **Flexível**: Métricas calculadas dinamicamente baseadas em filtros

---

## 🎯 Casos de Uso

### Cliente quer ver:
- ✅ Total de pontos ganhos vs gastos
- ✅ Quantos pontos tem pendentes
- ✅ Quantos estabelecimentos visitou
- ✅ Valor total gasto
- ✅ Média de pontos por compra

### Admin quer ver:
- ✅ Total de receita (baseado em filtros)
- ✅ Total de pontos dados
- ✅ Número de clientes únicos
- ✅ Número de estabelecimentos únicos
- ✅ Métricas agregadas por período/filtro

---

## 📈 Métricas Calculadas Automaticamente

### Pontos Líquidos (Net Points)
```
netPoints = totalEarned - totalSpent
```

Onde:
- `totalEarned` = soma de pontos de compras confirmadas
- `totalSpent` = pontos gastos + transferências enviadas + recompensas resgatadas

### Taxa de Conversão Média
```
avgConversionRate = (totalEarned / totalSpentConfirmed) * 100
```

### Pontos Pendentes
```
pendingPoints = totalPotential - totalEarned
```

Onde:
- `totalPotential` = soma de pontos de todas as compras
- `totalEarned` = soma de pontos de compras confirmadas

---

## 🔒 Segurança

- ✅ Métricas do usuário só retornadas para o próprio usuário
- ✅ Métricas agregadas (admin) calculadas sobre filtros aplicados
- ✅ Tratamento de erros sem expor informações sensíveis