# Regras de Segurança e Integridade de Dados

## 🛡️ Proteção de Integridade do Sistema

Este documento descreve as regras implementadas para proteger a integridade dos dados do sistema de pontos, especialmente relacionadas a estabelecimentos, usuários e compras.

---

## 📋 Regras de Estabelecimentos

### ❌ Deleção de Estabelecimento

**NÃO É PERMITIDO deletar um estabelecimento se:**

1. **Houver pelo menos uma compra confirmada (pontos já dados)**
   - **Motivo**: As compras confirmadas representam pontos já creditados aos clientes
   - **Impacto**: Deletar o estabelecimento comprometeria o histórico de pontos
   - **Solução**: Todos os pontos devem ser cancelados primeiro

2. **Houver compras pendentes**
   - **Motivo**: Compras pendentes estão aguardando aprovação
   - **Impacto**: Deletar o estabelecimento deixaria compras órfãs
   - **Solução**: Todas as compras devem ser canceladas ou processadas primeiro

**Exemplo de resposta de erro:**
```json
{
  "success": false,
  "error": "Não é possível deletar estabelecimento com compras confirmadas (pontos já dados). Todos os pontos devem ser cancelados primeiro.",
  "details": {
    "confirmedPurchases": 16,
    "totalPoints": 2840,
    "pendingPurchases": 3
  }
}
```

### ⚠️ Edição de Campos Críticos

**NÃO É PERMITIDO editar os seguintes campos se houver compras confirmadas:**

- `qr_code` - Código QR usado em compras
- `est_id` - ID do estabelecimento (referência em compras)
- `establishment_id` - ID do estabelecimento (referência em compras)

**Motivo**: Estes campos são referências críticas em transações de pontos. Alterá-los comprometeria a rastreabilidade das compras e pontos.

**Campos permitidos para edição (mesmo com compras confirmadas):**
- `name` - Nome do estabelecimento
- `type` - Tipo do estabelecimento
- `image_url` - Imagem principal
- `image_secondary` - Imagem secundária
- `address` - Endereço
- `phone` - Telefone
- `email` - Email
- `color` - Cor
- `is_active` - Status ativo/inativo

---

## 👤 Regras de Usuários

### ❌ Deleção de Usuário

**NÃO É PERMITIDO deletar um usuário se:**

1. **Houver pontos na carteira**
   - **Motivo**: Os pontos devem ser cancelados ou transferidos antes da deleção
   - **Impacto**: Deletar usuário com pontos causaria perda de dados de pontos
   - **Solução**: Transferir ou cancelar todos os pontos primeiro

2. **Houver compras confirmadas**
   - **Motivo**: Compras confirmadas criam histórico de pontos que deve ser preservado
   - **Impacto**: Deletar usuário comprometeria o histórico de transações
   - **Solução**: O histórico deve ser preservado para auditoria

**Exemplo de resposta de erro:**
```json
{
  "success": false,
  "error": "Não é possível deletar usuário com pontos na carteira. Os pontos devem ser cancelados ou transferidos primeiro.",
  "details": {
    "points": 1520,
    "balance": 0,
    "confirmedPurchases": 8
  }
}
```

---

## 🎯 Regras de Campanhas

### ❌ Deleção de Campanha

**NÃO É PERMITIDO deletar uma campanha se:**

- **Houver compras associadas à campanha**
  - **Motivo**: As campanhas definem a taxa de conversão de pontos nas compras
  - **Impacto**: Deletar campanha comprometeria o histórico de conversão
  - **Solução**: Preservar histórico de conversão de pontos

---

## ✅ Fluxo de Cancelamento de Pontos

Para deletar um estabelecimento ou usuário que tem compras confirmadas, o fluxo correto é:

1. **Cancelar todas as compras confirmadas**
   - Reverter os pontos creditados
   - Atualizar o status das compras para `cancelled`
   - Registrar no histórico de pontos

2. **Cancelar todas as compras pendentes**
   - Atualizar o status para `cancelled`
   - Não há pontos a reverter (ainda não foram creditados)

3. **Verificar que não há mais compras**
   - Confirmar que todas foram canceladas

4. **Deletar o estabelecimento/usuário**
   - Agora é permitido deletar

---

## 🔍 Validações Implementadas

### Endpoints Protegidos

1. **DELETE /api/establishments/:id**
   - Validação antes de deletar
   - Verifica compras confirmadas e pendentes

2. **PUT /api/establishments/:id**
   - Validação de campos críticos
   - Bloqueia edição de `qr_code`, `est_id`, `establishment_id` se houver compras confirmadas

3. **DELETE /api/users/:id**
   - Validação antes de deletar
   - Verifica pontos na carteira e compras confirmadas

### Métodos de Validação

- `Establishment.canDelete(id)` - Verifica se pode deletar estabelecimento
- `Establishment.canEditFields(id, updateData)` - Verifica se pode editar campos críticos
- `User.canDelete(id)` - Verifica se pode deletar usuário
- `validateCampaignDeletion(id)` - Verifica se pode deletar campanha

---

## 📊 Exemplo de Uso

### Tentativa de Deletar Estabelecimento com Compras

```javascript
// Request
DELETE /api/establishments/104

// Response (erro)
{
  "success": false,
  "error": "Não é possível deletar estabelecimento com compras confirmadas (pontos já dados). Todos os pontos devem ser cancelados primeiro.",
  "details": {
    "confirmedPurchases": 16,
    "totalPoints": 2840,
    "pendingPurchases": 3
  }
}
```

### Tentativa de Editar QR Code com Compras Confirmadas

```javascript
// Request
PUT /api/establishments/104
{
  "qrCode": "NOVO_QR_CODE"
}

// Response (erro)
{
  "success": false,
  "error": "Não é possível editar campos críticos (qr_code) quando há compras confirmadas. Estes campos são referências em transações de pontos.",
  "details": {
    "restrictedFields": ["qr_code"]
  }
}
```

---

## 🎯 Benefícios

1. **Integridade de Dados**: Garante que histórico de pontos não seja comprometido
2. **Rastreabilidade**: Mantém referências entre compras, estabelecimentos e pontos
3. **Auditoria**: Preserva histórico completo de transações
4. **Consistência**: Evita dados órfãos ou inconsistentes

---

## ⚠️ Importante

- **Estas regras são obrigatórias** e não podem ser ignoradas
- **Sempre cancele pontos** antes de deletar estabelecimentos/usuários com histórico
- **Use campos editáveis** para atualizar informações quando houver compras confirmadas
- **Preserve histórico** para auditoria e rastreabilidade