# 📊 Métricas Avançadas de Clientes

## 📋 **Visão Geral**

O endpoint `/api/users/customers` agora retorna **métricas avançadas e importantes** para o sistema de pontos/loyalty, incluindo:

- ✅ **Quantidade total de clientes**
- ✅ **Novos clientes** (hoje, últimos 7 dias, últimos 30 dias)
- ✅ **Clientes ativos/inativos**
- ✅ **Métricas de pontos** (total, média, máx/min)
- ✅ **Distribuição por nível** (Bronze, Silver, Gold, etc.)
- ✅ **Métricas de compras** (revenue, conversão, etc.)
- ✅ **Atividade de pontos** (ganhos/gastos)
- ✅ **E muito mais!**

## 🔗 **Endpoint**

```http
GET /api/users/customers
```

**Autenticação:** ✅ Requerida (Bearer Token)

**Parâmetros de Query:**
- `page` (opcional): Número da página (padrão: 1)
- `limit` (opcional): Itens por página (padrão: 10)
- `search` (opcional): Buscar por username, email, first_name ou last_name
- `is_active` (opcional): Filtrar por status ativo (`true`/`false`)

## 📊 **Resposta com Métricas Avançadas**

### **Estrutura da Resposta:**

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "username": "joao.silva",
      "email": "joao@example.com",
      "firstName": "João",
      "lastName": "Silva",
      "fullName": "João Silva",
      "phone": "+258841234567",
      "bi": "1234567890123",
      "isActive": true,
      "lastLogin": "2025-11-01T12:00:00.000Z",
      "createdAt": "2025-10-01T10:00:00.000Z",
      "points": 1250,
      "level": "Silver",
      "role": {
        "id": 1,
        "name": "user",
        "description": "Default user role"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  },
  "meta": {
    "showing": "1-10 de 50",
    "currentPage": 1,
    "perPage": 10,
    "type": "customers"
  },
  "metrics": {
    "total_customers": 50,
    "active_customers": 45,
    "inactive_customers": 5,
    "customers_with_login": 40,
    "customers_without_login": 10,
    "new_customers": {
      "today": 3,
      "last_7_days": 15,
      "last_30_days": 28
    },
    "active_customers_period": {
      "last_7_days": 35,
      "last_30_days": 42
    },
    "inactive_customers_last_30_days": 8,
    "points": {
      "total_points": 125000,
      "total_balance": 0,
      "customers_with_points": 38,
      "avg_points_per_customer": 3289.47,
      "max_points": 25000,
      "min_points": 0
    },
    "level_distribution": {
      "bronze": 20,
      "silver": 15,
      "gold": 8,
      "platinum": 5,
      "diamond": 2
    },
    "purchases": {
      "customers_with_purchases": 35,
      "total_purchases": 120,
      "total_revenue": 45000.50,
      "avg_purchases_per_customer": 3.43,
      "conversion_rate": 70.0,
      "purchases_last_7_days": 25,
      "purchases_last_30_days": 85
    },
    "points_activity": {
      "total_points_earned": 150000,
      "total_points_spent": 25000,
      "net_points": 125000,
      "avg_points_per_transaction": 1250.0
    },
    "calculated_at": "2025-11-01T12:00:00.000Z"
  }
}
```

## 📈 **Detalhamento das Métricas**

### **1. Métricas Básicas de Clientes**

| Métrica | Descrição |
|---------|-----------|
| `total_customers` | Total de clientes cadastrados |
| `active_customers` | Clientes com status ativo |
| `inactive_customers` | Clientes com status inativo |
| `customers_with_login` | Clientes que já fizeram login pelo menos uma vez |
| `customers_without_login` | Clientes que nunca fizeram login |

### **2. Novos Clientes**

| Métrica | Descrição |
|---------|-----------|
| `new_customers.today` | Novos clientes cadastrados hoje |
| `new_customers.last_7_days` | Novos clientes nos últimos 7 dias |
| `new_customers.last_30_days` | Novos clientes nos últimos 30 dias |

### **3. Clientes Ativos por Período**

| Métrica | Descrição |
|---------|-----------|
| `active_customers_period.last_7_days` | Clientes que fizeram login nos últimos 7 dias |
| `active_customers_period.last_30_days` | Clientes que fizeram login nos últimos 30 dias |
| `inactive_customers_last_30_days` | Clientes inativos há mais de 30 dias |

### **4. Métricas de Pontos**

| Métrica | Descrição |
|---------|-----------|
| `points.total_points` | Total de pontos acumulados por todos os clientes |
| `points.total_balance` | Total de saldo em carteira (se aplicável) |
| `points.customers_with_points` | Clientes que têm pontos acumulados (> 0) |
| `points.avg_points_per_customer` | Média de pontos por cliente |
| `points.max_points` | Maior quantidade de pontos de um cliente |
| `points.min_points` | Menor quantidade de pontos de um cliente |

### **5. Distribuição por Nível**

| Métrica | Descrição |
|---------|-----------|
| `level_distribution.bronze` | Quantidade de clientes no nível Bronze |
| `level_distribution.silver` | Quantidade de clientes no nível Silver |
| `level_distribution.gold` | Quantidade de clientes no nível Gold |
| `level_distribution.platinum` | Quantidade de clientes no nível Platinum |
| `level_distribution.diamond` | Quantidade de clientes no nível Diamond |

**Níveis disponíveis:** bronze, silver, gold, platinum, diamond

### **6. Métricas de Compras**

| Métrica | Descrição |
|---------|-----------|
| `purchases.customers_with_purchases` | Clientes que já fizeram pelo menos uma compra |
| `purchases.total_purchases` | Total de compras realizadas |
| `purchases.total_revenue` | Receita total gerada pelas compras |
| `purchases.avg_purchases_per_customer` | Média de compras por cliente |
| `purchases.conversion_rate` | Taxa de conversão (% de clientes que fizeram compras) |
| `purchases.purchases_last_7_days` | Compras nos últimos 7 dias |
| `purchases.purchases_last_30_days` | Compras nos últimos 30 dias |

### **7. Atividade de Pontos**

| Métrica | Descrição |
|---------|-----------|
| `points_activity.total_points_earned` | Total de pontos ganhos (acumulados) |
| `points_activity.total_points_spent` | Total de pontos gastos (usados/resgatados) |
| `points_activity.net_points` | Saldo líquido (ganhos - gastos) |
| `points_activity.avg_points_per_transaction` | Média de pontos por transação |

### **8. Metadados**

| Métrica | Descrição |
|---------|-----------|
| `calculated_at` | Data/hora em que as métricas foram calculadas (ISO 8601) |

## 🎯 **Casos de Uso**

### **Caso 1: Dashboard de Clientes**
```javascript
GET /api/users/customers?page=1&limit=10
// Retorna lista de clientes + métricas avançadas para dashboard
```

### **Caso 2: Relatório de Novos Clientes**
```javascript
// Usar metrics.new_customers para relatório
// Útil para acompanhar crescimento da base de clientes
```

### **Caso 3: Análise de Engajamento**
```javascript
// Usar metrics.active_customers_period
// Útil para identificar clientes ativos vs inativos
```

### **Caso 4: Performance de Pontos**
```javascript
// Usar metrics.points e metrics.points_activity
// Útil para entender como os clientes estão usando os pontos
```

### **Caso 5: Análise de Conversão**
```javascript
// Usar metrics.purchases.conversion_rate
// Útil para entender quantos clientes realmente fazem compras
```

## 📝 **Notas Técnicas**

### **Tabelas Utilizadas:**

As métricas são calculadas dinamicamente baseadas nas tabelas disponíveis:

- ✅ **Sempre utilizadas:** `users`, `roles`
- ✅ **Se disponíveis:** `users_profile`, `wallets`, `points_history`, `purchases`

### **Comportamento Dinâmico:**

- Se uma tabela não existir, a métrica relacionada retorna valores padrão (0, {}, etc.)
- O sistema verifica automaticamente a existência das tabelas antes de calcular métricas
- Métricas são calculadas em paralelo com a busca da lista de clientes para melhor performance

### **Performance:**

- As métricas são calculadas de forma eficiente usando agregações SQL
- Cálculos são feitos em paralelo com a busca da lista de clientes
- Se houver erro no cálculo das métricas, a lista de clientes ainda é retornada

## ⚠️ **Tratamento de Erros**

Se houver erro ao calcular as métricas avançadas:

```json
{
  "success": true,
  "data": [...], // Lista de clientes ainda é retornada
  "pagination": {...},
  "meta": {...},
  "metrics": {
    "message": "Métricas avançadas não disponíveis"
  }
}
```

## ✅ **Resumo**

O endpoint `/api/users/customers` agora fornece:

✅ Lista paginada de clientes  
✅ **Métricas avançadas e importantes** para o sistema de pontos  
✅ **Informações em tempo real** sobre o desempenho do programa de fidelidade  
✅ **Dados para dashboards e relatórios** de gestão  

Tudo em uma única requisição! 🚀