# Campanhas de Desconto por Marcação

## 📋 Descrição

Sistema completo para gerenciar campanhas de desconto por marcação (reserva). Permite que estabelecimentos criem campanhas onde clientes podem fazer reservas e receber vouchers com descontos.

**Nome da Campanha:** "Campanha Oferta de Desconto por marcacao"

## 🗄️ Estrutura do Banco de Dados

### Tabelas Criadas

1. **discount_reservation_campaigns** - Armazena as campanhas
2. **discount_reservation_vouchers** - Armazena os vouchers/reservas dos clientes

### Script de Criação

Execute o script para criar as tabelas:

```bash
node scripts/create-discount-reservation-campaigns-tables.js
```

## 📝 Campos da Campanha

### Campos Obrigatórios

- `consumo_minimo`: Valor mínimo de consumo em MZN (deve ser > 0)
- `data_inicial`: Data de início da campanha (ISO 8601)
- `data_final`: Data de término da campanha (deve ser posterior a data_inicial)
- `limite_utilizacao_cliente`: Limite de vezes que um cliente pode **reservar** na mesma campanha (deve ser > 0)
  - Exemplo: Se limite = 3, o cliente pode fazer 3 reservas na mesma campanha
- `establishment_id`: ID do estabelecimento
- `campaign_name`: Nome da campanha (o benefício é descrito aqui, ex: "Desconto de 40%" ou "Compre 3 leve mais 1")

### Campos Opcionais

- `percentual_desconto`: Percentual de desconto (0-100) - ex: 40 para 40% de desconto
  - Se informado: aplica desconto percentual
  - Se não informado: assume promoção "compre X leve Y" (conforme descrito no `campaign_name`)
- `dias_antes_reserva`: Quantos dias antes da data final pode fazer reserva (default: 0)
- `is_active`: Se a campanha está ativa (default: true)

**IMPORTANTE:** O benefício é descrito no `campaign_name`. 
- Se informar `percentual_desconto`: aplica desconto percentual
- Se não informar: assume promoção "compre X leve Y" (ex: "Compre 3 leve mais 1")


### Exemplo de Campanha

**Exemplo 1 - Desconto Percentual:**

```json
{
  "consumo_minimo": 5000,
  "data_inicial": "2024-01-01T00:00:00Z",
  "data_final": "2024-12-31T23:59:59Z",
  "limite_utilizacao_cliente": 3,
  "percentual_desconto": 40,
  "establishment_id": 1,
  "campaign_name": "Reserve um quarto por 3 dias seguidos dentro do prazo da campanha e terá desconto de 40%"
}
```

**Exemplo 2 - Compre X Leve Y (sem percentual_desconto):**

```json
{
  "consumo_minimo": 1000,
  "data_inicial": "2024-01-01T00:00:00Z",
  "data_final": "2024-12-31T23:59:59Z",
  "limite_utilizacao_cliente": 5,
  "establishment_id": 1,
  "campaign_name": "Compre 3 leve mais 1 grátis"
}
```

## 🚀 Endpoints da API

### Base URL
```
/api/discount-reservation-campaigns
```

### 1. Criar Campanha

**POST** `/api/discount-reservation-campaigns`

**Autenticação:** Requerida (Admin ou Merchant)

**Body:**
```json
{
  "tipo_beneficio": "desconto_percentual",
  "consumo_minimo": 2000,
  "data_inicial": "2024-01-01T00:00:00Z",
  "data_final": "2024-12-31T23:59:59Z",
  "limite_utilizacao_cliente": 3,
  "percentual_desconto": 43,
  "establishment_id": 1,
  "campaign_name": "Reserve 5 dias antes e ganhe 43% de desconto em compras acima de 2M"
}
```

**Resposta:**
```json
{
  "success": true,
  "message": "Campanha criada com sucesso",
  "data": {
    "id": "uuid-da-campanha",
    "campaign_number": "DISC-RES-...",
    "campaign_name": "Campanha Oferta de Desconto por marcacao",
    ...
  }
}
```

**Nota:** Quando uma campanha é criada, todos os clientes ativos recebem uma notificação push.

### 2. Listar Campanhas

**GET** `/api/discount-reservation-campaigns`

**Query Parameters:**
- `page`: Número da página (default: 1)
- `limit`: Itens por página (default: 10)
- `establishment_id`: Filtrar por estabelecimento
- `is_active`: Filtrar por status (true/false)

### 3. Obter Campanha por ID

**GET** `/api/discount-reservation-campaigns/:id`

### 4. Atualizar Campanha

**PUT** `/api/discount-reservation-campaigns/:id`

**Autenticação:** Requerida (Admin ou Merchant)

### 5. Deletar Campanha

**DELETE** `/api/discount-reservation-campaigns/:id`

**Autenticação:** Requerida (Admin ou Merchant)

**Nota:** Só pode deletar se não houver reservas ativas.

### 6. Fazer Reserva (Cliente)

**POST** `/api/discount-reservation-campaigns/reservations`

**Autenticação:** Requerida (Cliente)

**Body:**
```json
{
  "campaign_id": "uuid-da-campanha"
}
```

**Validações:**
- Não pode reservar após a data final
- Se `dias_antes_reserva` estiver configurado, deve reservar pelo menos esse número de dias antes da data final
- Não pode exceder o `limite_utilizacao_cliente` (total de reservas na mesma campanha)
- Um cliente pode fazer múltiplas reservas na mesma campanha, até atingir o limite

**Resposta:**
```json
{
  "success": true,
  "message": "Reserva criada com sucesso",
  "data": {
    "voucher_id": "uuid-do-voucher",
    "voucher_code": "VCH-...",
    "status": "reserved",
    "campaign": { ... },
    "reserved_at": "2024-01-01T00:00:00Z",
    "expires_at": "2024-12-31T23:59:59Z"
  }
}
```

**Nota:** Quando uma reserva é criada, o cliente recebe uma notificação com o código do voucher.

### 7. Listar Minhas Reservas

**GET** `/api/discount-reservation-campaigns/reservations/my`

**Autenticação:** Requerida (Cliente)

**Query Parameters:**
- `status`: Filtrar por status (`reserved`, `used`, `cancelled`, `expired`)

### 8. Usar Voucher

**POST** `/api/discount-reservation-campaigns/vouchers/use`

**Autenticação:** Requerida (Cliente)

**Body:**
```json
{
  "voucher_code": "VCH-...",
  "purchase_amount": 2500
}
```

**Validações:**
- Voucher deve estar no status `reserved`
- Data final da campanha não pode ter passado
- `purchase_amount` deve ser >= `consumo_minimo`

**Resposta:**
```json
{
  "success": true,
  "message": "Voucher utilizado com sucesso",
  "data": {
    "voucher_code": "VCH-...",
    "purchase_amount": 2500,
    "discount_amount": 1075,
    "final_amount": 1425,
    "used_at": "2024-01-15T10:30:00Z"
  }
}
```

## 🔄 Fluxo Completo

1. **Admin/Merchant cria campanha**
   - Define tipo de benefício, consumo mínimo, datas, etc.
   - Todos os clientes recebem notificação

2. **Cliente faz reserva**
   - Cliente escolhe a campanha
   - Sistema valida datas e limites
   - Gera código de voucher único
   - Cliente recebe notificação com o código

3. **Cliente usa o voucher**
   - Cliente faz compra no estabelecimento
   - Informa o código do voucher
   - Sistema valida e aplica desconto
   - Voucher é marcado como usado

## 📊 Status dos Vouchers

- `reserved`: Reservado, aguardando uso
- `used`: Já foi utilizado
- `cancelled`: Cancelado
- `expired`: Expirado (após data final)

## 🔔 Notificações

### Quando Campanha é Criada
- Todos os clientes ativos recebem notificação push
- Tipo: `new_discount_campaign`

### Quando Reserva é Criada
- Cliente recebe notificação com código do voucher
- Tipo: `discount_reservation_created`

## ⚠️ Validações Importantes

1. **Data Final:** Não é possível fazer reserva após a data final
2. **Dias Antes da Reserva:** Se configurado, deve reservar pelo menos `dias_antes_reserva` dias antes da data final (opcional, default: 0)
3. **Limite por Cliente:** Cada cliente pode fazer no máximo `limite_utilizacao_cliente` reservas na mesma campanha
   - Exemplo: Se limite = 3, o cliente pode fazer 3 reservas diferentes
4. **Consumo Mínimo:** Valor da compra deve ser >= `consumo_minimo`
5. **Tipo de Benefício:** 
   - O benefício é descrito no `campaign_name`
   - Se informar `percentual_desconto`: aplica desconto percentual
   - Se não informar: assume promoção "compre X leve Y" (conforme descrito no `campaign_name`)

## 🛠️ Exemplo de Uso Completo

### 1. Criar Campanha
```bash
curl -X POST http://localhost:8000/api/discount-reservation-campaigns \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_beneficio": "desconto_percentual",
    "consumo_minimo": 2000,
    "data_inicial": "2024-01-01T00:00:00Z",
    "data_final": "2024-12-31T23:59:59Z",
    "limite_utilizacao_cliente": 1,
    "dias_antes_reserva": 5,
    "percentual_desconto": 43,
    "establishment_id": 1,
    "campaign_name": "Reserve 5 dias antes e ganhe 43% de desconto"
  }'
```

### 2. Cliente Faz Reserva
```bash
curl -X POST http://localhost:8000/api/discount-reservation-campaigns/reservations \
  -H "Authorization: Bearer CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "uuid-da-campanha"
  }'
```

### 3. Cliente Usa Voucher
```bash
curl -X POST http://localhost:8000/api/discount-reservation-campaigns/vouchers/use \
  -H "Authorization: Bearer CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "voucher_code": "VCH-...",
    "purchase_amount": 2500
  }'
```

## 📌 Observações

- O sistema gera códigos de voucher únicos automaticamente
- Notificações são enviadas via Socket.io (tempo real) e FCM (push)
- Todas as operações são auditadas e logadas
- O sistema valida todas as regras de negócio antes de permitir ações