# 🔐 Auditoria de Aprovações de Compras

## 📋 Resumo

Implementado sistema completo de auditoria para aprovações e rejeições de compras, garantindo que quem faz a aprovação seja registrado para auditoria e rastreabilidade.

---

## ✅ Implementação

### **1. Registro de Aprovação (Confirmar Compra)**

#### **Campos Salvos na Tabela `purchases`:**
- ✅ `confirmed_by` - ID do usuário que aprovou
- ✅ `confirmed_at` - Data/hora da aprovação
- ✅ `status` - Alterado para `'confirmed'`

#### **Registro de Auditoria:**
- ✅ Log na tabela `audit_logs` com:
  - **Action**: `APPROVE`
  - **Entity Type**: `PURCHASE`
  - **Entity ID**: ID da compra
  - **User ID**: ID do usuário que aprovou
  - **Old Values**: Estado anterior da compra
  - **New Values**: Estado após aprovação (inclui `confirmed_by` e `confirmed_at`)
  - **IP Address**: IP do usuário que aprovou
  - **Timestamp**: Data/hora da aprovação

---

### **2. Registro de Rejeição (Rejeitar Compra)**

#### **Campos Salvos na Tabela `purchases`:**
- ✅ `confirmed_by` ou `rejected_by` - ID do usuário que rejeitou (usa `confirmed_by` como fallback se `rejected_by` não existir)
- ✅ `notes` - Motivo da rejeição (se fornecido)
- ✅ `status` - Alterado para `'rejected'`

#### **Registro de Auditoria:**
- ✅ Log na tabela `audit_logs` com:
  - **Action**: `REJECT`
  - **Entity Type**: `PURCHASE`
  - **Entity ID**: ID da compra
  - **User ID**: ID do usuário que rejeitou
  - **Old Values**: Estado anterior da compra
  - **New Values**: Estado após rejeição (inclui `rejected_by` e `notes`)
  - **IP Address**: IP do usuário que rejeitou
  - **Timestamp**: Data/hora da rejeição

---

## 🔍 Estrutura dos Logs de Auditoria

### **Exemplo de Log de Aprovação:**
```json
{
  "action": "APPROVE",
  "entity_type": "PURCHASE",
  "entity_id": 123,
  "user_id": 5,
  "username": "admin_user",
  "old_values": {
    "status": "pending",
    "purchase_code": "COMPRA_1234567890_ABC123",
    "user_id": "100",
    "establishment_id": 5,
    "purchase_amount": 150.50,
    "points_earned": 30
  },
  "new_values": {
    "status": "confirmed",
    "purchase_code": "COMPRA_1234567890_ABC123",
    "confirmed_by": 5,
    "confirmed_at": "2024-01-15T10:30:00Z",
    "user_id": "100",
    "establishment_id": 5,
    "purchase_amount": 150.50,
    "points_earned": 30
  },
  "ip_address": "192.168.1.100",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### **Exemplo de Log de Rejeição:**
```json
{
  "action": "REJECT",
  "entity_type": "PURCHASE",
  "entity_id": 124,
  "user_id": 5,
  "username": "admin_user",
  "old_values": {
    "status": "pending",
    "purchase_code": "COMPRA_1234567890_XYZ789",
    "user_id": "101",
    "establishment_id": 5,
    "purchase_amount": 200.00,
    "points_earned": 40
  },
  "new_values": {
    "status": "rejected",
    "purchase_code": "COMPRA_1234567890_XYZ789",
    "rejected_by": 5,
    "notes": "Valor não confere com o recibo",
    "user_id": "101",
    "establishment_id": 5,
    "purchase_amount": 200.00,
    "points_earned": 40
  },
  "ip_address": "192.168.1.100",
  "timestamp": "2024-01-15T10:35:00Z"
}
```

---

## 📊 Informações Registradas

### **Para Cada Aprovação/Rejeição:**

1. **Quem aprovou/rejeitou:**
   - ✅ User ID
   - ✅ Username
   - ✅ IP Address

2. **Quando:**
   - ✅ Timestamp exato

3. **O que foi aprovado/rejeitado:**
   - ✅ ID da compra
   - ✅ Código da compra
   - ✅ Estado anterior
   - ✅ Estado posterior
   - ✅ Detalhes da compra (valor, pontos, estabelecimento, cliente)

4. **Contexto:**
   - ✅ IP do usuário
   - ✅ User Agent
   - ✅ Endpoint usado
   - ✅ Método HTTP

---

## 🎯 Endpoints Afetados

### **POST /api/purchases/:id/confirm** (Aprovar Compra)
- ✅ Salva `confirmed_by` na tabela `purchases`
- ✅ Salva `confirmed_at` na tabela `purchases`
- ✅ Cria log de auditoria na tabela `audit_logs`
- ✅ Retorna `confirmed_by` na resposta

### **POST /api/purchases/:id/reject** (Rejeitar Compra)
- ✅ Salva `confirmed_by` ou `rejected_by` na tabela `purchases`
- ✅ Salva motivo da rejeição em `notes`
- ✅ Cria log de auditoria na tabela `audit_logs`
- ✅ Retorna informações da rejeição na resposta

---

## 🔒 Rastreabilidade Completa

### **Para Auditoria, Você Pode Consultar:**

1. **Tabela `purchases`:**
   ```sql
   SELECT 
       purchase_id,
       purchase_code,
       status,
       confirmed_by,
       confirmed_at,
       notes
   FROM purchases
   WHERE status IN ('confirmed', 'rejected')
   ```

2. **Tabela `audit_logs`:**
   ```sql
   SELECT 
       action,
       entity_type,
       entity_id,
       user_id,
       username,
       old_values,
       new_values,
       ip_address,
       created_at
   FROM audit_logs
   WHERE entity_type = 'PURCHASE'
   AND action IN ('APPROVE', 'REJECT')
   ORDER BY created_at DESC
   ```

---

## ✅ Benefícios

1. ✅ **Rastreabilidade Total**: Sempre sabemos quem aprovou/rejeitou cada compra
2. ✅ **Auditoria Completa**: Histórico completo de mudanças de status
3. ✅ **Segurança**: IP e informações do usuário registradas
4. ✅ **Compliance**: Atende requisitos de auditoria e compliance
5. ✅ **Transparência**: Cliente pode ver quem aprovou sua compra (se aplicável)
6. ✅ **Accountability**: Cada aprovação/rejeição tem um responsável identificado

---

## 📝 Exemplo de Resposta da API

### **Aprovar Compra:**
```json
{
  "success": true,
  "data": {
    "purchase_id": 123,
    "purchase_code": "COMPRA_1234567890_ABC123",
    "status": "confirmed",
    "points_earned": 30,
    "confirmed_at": "2024-01-15T10:30:00Z",
    "confirmed_by": 5
  },
  "message": "Compra confirmada! 30 pontos adicionados à carteira do cliente."
}
```

### **Rejeitar Compra:**
```json
{
  "success": true,
  "data": {
    "purchase_id": 124,
    "purchase_code": "COMPRA_1234567890_XYZ789",
    "status": "rejected",
    "notes": "Valor não confere com o recibo"
  },
  "message": "Compra rejeitada com sucesso"
}
```

---

## 🔍 Verificação

Para verificar se a auditoria está funcionando:

```sql
-- Ver últimas aprovações
SELECT 
    al.action,
    al.entity_id as purchase_id,
    al.user_id as approved_by_user_id,
    al.username as approved_by_username,
    al.created_at as approval_time,
    al.ip_address,
    (al.new_values->>'confirmed_by')::int as confirmed_by,
    (al.new_values->>'confirmed_at')::timestamp as confirmed_at
FROM audit_logs al
WHERE al.entity_type = 'PURCHASE'
AND al.action = 'APPROVE'
ORDER BY al.created_at DESC
LIMIT 10;

-- Ver últimas rejeições
SELECT 
    al.action,
    al.entity_id as purchase_id,
    al.user_id as rejected_by_user_id,
    al.username as rejected_by_username,
    al.created_at as rejection_time,
    al.ip_address,
    (al.new_values->>'notes')::text as rejection_reason
FROM audit_logs al
WHERE al.entity_type = 'PURCHASE'
AND al.action = 'REJECT'
ORDER BY al.created_at DESC
LIMIT 10;
```

---

## ⚠️ Importante

- ✅ Logs de auditoria são criados **ANTES** de retornar resposta ao cliente
- ✅ Se o log de auditoria falhar, a aprovação/rejeição ainda é processada (não interrompe o fluxo)
- ✅ Apenas um aviso é registrado no logger se o log de auditoria falhar
- ✅ Todos os campos necessários para auditoria são salvos na tabela `purchases`
- ✅ Histórico completo disponível na tabela `audit_logs`