# 🎯 **SISTEMA DE QR CODE E PONTOS POR COMPRAS**

## 📋 **DESCRIÇÃO**

Sistema completo para geração automática de QR codes para estabelecimentos e atribuição de pontos aos clientes quando fazem compras e escaneiam o QR code do estabelecimento.

---

## 🏗️ **COMPONENTES IMPLEMENTADOS**

### 1. **Utilitário de Geração de QR Code** (`utils/qrCodeGenerator.js`)

- **Função `generateQRCode(establishmentId, establishmentType)`:**
  - Gera QR code único no formato: `MAKTUBIA_{TYPE}_{ID}_{HASH}`
  - Utiliza MD5 para criar hash único
  - Formato: `MAKTUBIA_RESTAURANT_1_A1B2C3D4`

- **Função `isValidQRCodeFormat(qrCode)`:**
  - Valida se o QR code tem formato correto
  - Pattern: `/^MAKTUBIA_[A-Z0-9_]+_\d+_[A-Z0-9]+$/`

- **Função `extractEstablishmentId(qrCode)`:**
  - Extrai o ID do estabelecimento do QR code
  - Retorna `null` se o formato for inválido

### 2. **Modelo de Compras** (`models/PurchasesModel.js`)

- **Função `create(purchaseData)`:**
  - Cria compra e adiciona pontos automaticamente
  - Calcula pontos: `(valor da compra * taxa de conversão) * multiplicador de bônus`
  - Atualiza carteira do usuário
  - Registra no histórico de pontos
  - Usa transação para garantir consistência

- **Função `findByUserId(userId, options)`:**
  - Lista compras de um usuário com paginação
  - Suporta filtro por estabelecimento

- **Função `findById(purchaseId)`:**
  - Busca compra específica por ID

- **Função `findByEstablishmentId(establishmentId, options)`:**
  - Lista compras de um estabelecimento

- **Função `findByQRCode(qrCode, options)`:**
  - Lista compras por QR code

### 3. **Controller de Compras** (`controllers/purchaseController.js`)

- **`scanQRCode` - POST `/api/purchases/scan`:**
  - Processa scan de QR code e registra compra
  - Valida QR code e estabelecimento
  - Busca campanha ativa do estabelecimento
  - Calcula pontos baseado em campanha ou padrão (20%)
  - Verifica gasto mínimo se houver campanha
  - Retorna compra criada e pontos ganhos

- **`getMyPurchases` - GET `/api/purchases/my-purchases`:**
  - Lista compras do usuário autenticado
  - Suporta paginação e filtro por estabelecimento

- **`getPurchase` - GET `/api/purchases/:id`:**
  - Busca compra específica
  - Verifica permissões (usuário ou admin)

### 4. **Rotas de Compras** (`routes/purchaseRoutes.js`)

- `POST /api/purchases/scan` - Escanear QR code e processar compra
- `GET /api/purchases/my-purchases` - Listar compras do usuário
- `GET /api/purchases/:id` - Obter compra específica

### 5. **Atualização do Controller de Estabelecimentos**

- **Geração automática de QR code:**
  - Quando um estabelecimento é criado sem QR code, gera automaticamente
  - Usa ID do estabelecimento e tipo para criar QR code único
  - Atualiza estabelecimento após criação para garantir QR code correto

### 6. **Script de Migração** (`create-purchases-table.js`)

- Cria tabela `purchases` com estrutura completa:
  - `purchase_id` (SERIAL PRIMARY KEY)
  - `user_id` (VARCHAR(64) - referência a users_profile)
  - `establishment_id` (INTEGER - referência a establishments)
  - `qr_code` (VARCHAR(100))
  - `purchase_amount` (NUMERIC(14,2))
  - `conversion_rate` (NUMERIC(10,4) - padrão 0.2)
  - `bonus_multiplier` (NUMERIC(10,2) - padrão 1.0)
  - `points_earned` (BIGINT)
  - `purchase_date` (TIMESTAMP)
  - `notes` (TEXT)
  - `created_at` (TIMESTAMP)

- Cria índices para performance:
  - `idx_purchases_user_id`
  - `idx_purchases_establishment_id`
  - `idx_purchases_qr_code`
  - `idx_purchases_purchase_date`

---

## 📊 **FLUXO DE FUNCIONAMENTO**

### **Criação de Estabelecimento:**
1. Admin cria estabelecimento
2. Sistema gera QR code automaticamente se não fornecido
3. QR code é salvo no banco de dados
4. QR code é retornado na resposta

### **Compra pelo Cliente:**
1. Cliente faz compra no estabelecimento
2. Cliente escaneia QR code do estabelecimento via app
3. App envia requisição: `POST /api/purchases/scan`
   ```json
   {
     "qrCode": "MAKTUBIA_RESTAURANT_1_A1B2C3D4",
     "purchaseAmount": 100.50
   }
   ```
4. Sistema valida QR code e estabelecimento
5. Sistema busca campanha ativa do estabelecimento
6. Sistema calcula pontos:
   - Taxa de conversão: 20% (padrão) ou da campanha
   - Multiplicador de bônus: 1.0 (padrão) ou da campanha
   - Exemplo: R$ 100,50 * 0.20 * 1.0 = 20 pontos
7. Sistema adiciona pontos à carteira do cliente
8. Sistema registra compra na tabela `purchases`
9. Sistema registra histórico na tabela `points_history`
10. Sistema retorna compra com pontos ganhos

---

## 🔧 **CONFIGURAÇÃO E USO**

### **1. Criar Tabela de Compras:**
```bash
node create-purchases-table.js
```

### **2. Criar Estabelecimento:**
```bash
POST /api/establishments
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Restaurante Sabor",
  "type": "Restaurante",
  "address": "Rua das Flores, 123",
  "phone": "+258841234567"
}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Restaurante Sabor",
    "qrCode": "MAKTUBIA_RESTAURANT_1_A1B2C3D4",
    ...
  }
}
```

### **3. Escanear QR Code e Processar Compra:**
```bash
POST /api/purchases/scan
Authorization: Bearer {token}
Content-Type: application/json

{
  "qrCode": "MAKTUBIA_RESTAURANT_1_A1B2C3D4",
  "purchaseAmount": 100.50
}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "purchase_id": 1,
    "establishment_id": 1,
    "establishment_name": "Restaurante Sabor",
    "purchase_amount": 100.50,
    "points_earned": 20,
    "total_points": 120,
    "purchase_date": "2024-01-15T10:30:00Z",
    "campaign": {
      "id": 1,
      "type": "points_per_spend",
      "conversion_rate": 0.2,
      "bonus_multiplier": 1.0
    }
  },
  "message": "Compra registrada! Você ganhou 20 pontos."
}
```

### **4. Listar Compras do Usuário:**
```bash
GET /api/purchases/my-purchases?page=1&limit=20
Authorization: Bearer {token}
```

**Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "purchase_id": 1,
      "establishment_name": "Restaurante Sabor",
      "purchase_amount": 100.50,
      "points_earned": 20,
      "purchase_date": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}
```

---

## 📈 **CÁLCULO DE PONTOS**

### **Fórmula:**
```
Pontos = floor(Valor da Compra × Taxa de Conversão × Multiplicador de Bônus)
```

### **Exemplos:**

**Sem campanha (padrão):**
- Compra: R$ 100,00
- Taxa: 20% (0.2)
- Multiplicador: 1.0
- **Pontos ganhos: 20**

**Com campanha:**
- Compra: R$ 100,00
- Taxa: 25% (0.25)
- Multiplicador: 2.0 (2x pontos)
- **Pontos ganhos: 50**

**Com gasto mínimo:**
- Campanha: Gasto mínimo R$ 50,00
- Compra: R$ 30,00
- **Resultado: Erro - valor abaixo do mínimo**

---

## 🔐 **SEGURANÇA**

- Todas as rotas requerem autenticação (`isAuthenticated`)
- QR codes são validados antes de processar compra
- Estabelecimentos inativos são rejeitados
- Validação de gasto mínimo quando há campanha ativa
- Histórico completo de transações
- Logs de auditoria para todas as ações

---

## 📝 **OBSERVAÇÕES**

1. **QR Code único:** Cada estabelecimento tem QR code único gerado automaticamente
2. **Campanhas:** Sistema busca campanha ativa do estabelecimento automaticamente
3. **Transações:** Uso de transações SQL para garantir consistência
4. **Histórico:** Todas as compras são registradas no histórico de pontos
5. **Wallet:** Carteira do usuário é criada automaticamente se não existir

---

## 🚀 **PRÓXIMOS PASSOS SUGERIDOS**

1. Adicionar validação de limite de compras por dia
2. Implementar sistema de recompensas baseado em pontos acumulados
3. Adicionar notificações push quando pontos são adicionados
4. Criar dashboard de compras para estabelecimentos
5. Implementar sistema de cashback adicional