# 🛒 **FLUXO DE COMPRA E PONTOS - SISTEMA ATUALIZADO**

## 📋 **DESCRIÇÃO DO FLUXO**

Como as compras são feitas **fisicamente** no estabelecimento (não no app), o sistema agora funciona com **confirmação do estabelecimento**.

---

## 🔄 **FLUXO COMPLETO**

### **1. Cliente faz compra física no estabelecimento**
- Cliente compra no estabelecimento (dinheiro, cartão, etc.)
- Cliente recebe nota fiscal/cupom

### **2. Cliente escaneia QR code do estabelecimento**
- Cliente abre o app e escaneia o QR code do estabelecimento
- Cliente informa o valor da compra
- Sistema cria compra com status `pending` (pendente)
- Sistema gera código único da compra (`COMPRA_{TIMESTAMP}_{HASH}`)
- **Pontos ainda NÃO são adicionados**

### **3. Estabelecimento confirma a compra**
- Estabelecimento recebe notificação ou verifica compras pendentes
- Estabelecimento confirma a compra (via app ou sistema)
- Sistema valida e muda status para `confirmed`
- **Agora os pontos são adicionados à carteira do cliente**

### **4. Cliente recebe pontos**
- Cliente recebe notificação de confirmação
- Pontos aparecem na carteira

---

## 📱 **ENDPOINTS**

### **1. Cliente escaneia QR code e registra compra**
```bash
POST /api/purchases/scan
Authorization: Bearer {token_cliente}
Content-Type: application/json

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

**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": "pending",
    "purchase_date": "2024-01-15T10:30:00Z"
  },
  "message": "Compra registrada! Código: COMPRA_1234567890_ABC123. Aguardando confirmação do estabelecimento para receber 20 pontos."
}
```

### **2. Estabelecimento confirma compra**
```bash
POST /api/purchases/1/confirm
Authorization: Bearer {token_estabelecimento}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "purchase_id": 1,
    "purchase_code": "COMPRA_1234567890_ABC123",
    "status": "confirmed",
    "points_earned": 20,
    "confirmed_at": "2024-01-15T10:35:00Z"
  },
  "message": "Compra confirmada! 20 pontos adicionados à carteira do cliente."
}
```

### **3. Estabelecimento rejeita compra**
```bash
POST /api/purchases/1/reject
Authorization: Bearer {token_estabelecimento}
Content-Type: application/json

{
  "reason": "Valor não corresponde à compra real"
}
```

### **4. Estabelecimento lista compras pendentes**
```bash
GET /api/purchases/establishment/1/pending?page=1&limit=20
Authorization: Bearer {token_estabelecimento}
```

**Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "purchase_id": 1,
      "purchase_code": "COMPRA_1234567890_ABC123",
      "user_name": "João Silva",
      "user_email": "joao@example.com",
      "purchase_amount": 100.50,
      "points_earned": 20,
      "purchase_date": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

### **5. Cliente lista suas compras**
```bash
GET /api/purchases/my-purchases?page=1&limit=20
Authorization: Bearer {token_cliente}
```

**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",
      "purchase_date": "2024-01-15T10:30:00Z",
      "confirmed_at": "2024-01-15T10:35:00Z"
    }
  ]
}
```

---

## 🔐 **SEGURANÇA E VALIDAÇÃO**

### **Status da Compra:**
- **`pending`**: Compra registrada, aguardando confirmação (padrão)
- **`confirmed`**: Compra confirmada pelo estabelecimento (pontos adicionados)
- **`rejected`**: Compra rejeitada pelo estabelecimento
- **`cancelled`**: Compra cancelada

### **Validações:**
1. **Cliente só pode escanear QR code**: Não pode confirmar próprias compras
2. **Estabelecimento só confirma suas compras**: Verificação de permissão
3. **Pontos só são adicionados após confirmação**: Previne fraude
4. **Código único por compra**: Previne duplicação

---

## 💡 **VANTAGENS DESTE FLUXO**

1. **Previne fraude**: Cliente não pode adicionar pontos sozinho
2. **Validação do estabelecimento**: Confirma valor real da compra
3. **Rastreabilidade**: Histórico completo de compras e confirmações
4. **Flexibilidade**: Estabelecimento pode rejeitar compras inválidas
5. **Transparência**: Cliente vê status da compra em tempo real

---

## 📊 **ESTRUTURA DA TABELA**

A tabela `purchases` agora inclui:
- `purchase_code`: Código único da compra
- `status`: Status da compra (pending, confirmed, rejected, cancelled)
- `confirmed_at`: Data/hora da confirmação
- `confirmed_by`: ID do usuário que confirmou

---

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

1. **Notificações push**: Notificar cliente quando compra for confirmada
2. **QR code na nota fiscal**: Estabelecimento pode gerar QR code único por compra
3. **Integração com sistema de caixa**: Confirmar compras automaticamente
4. **Dashboard para estabelecimentos**: Visualizar e gerenciar compras pendentes
5. **Limite de tempo**: Compras pendentes expiram após X horas