# 🏪 Sistema de Merchants

## 📋 Visão Geral

O sistema de merchants permite que usuários sejam associados a estabelecimentos e possam criar campanhas para seus clientes ganharem pontos. O sistema inclui controle de permissões onde apenas admin pode conceder permissões a merchants para criar campanhas e definir pontos personalizados.

## 🗄️ Estrutura do Banco de Dados

### Tabela `merchants`

```sql
CREATE TABLE merchants (
    merchant_id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
    establishment_id INTEGER NOT NULL REFERENCES establishments(establishment_id) ON DELETE CASCADE,
    can_create_campaigns BOOLEAN DEFAULT FALSE,  -- Permissão para criar campanhas
    can_set_custom_points BOOLEAN DEFAULT FALSE, -- Permissão para definir pontos personalizados
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by INTEGER REFERENCES users(user_id),
    UNIQUE(user_id, establishment_id)
);
```

### Campos Adicionados em `campaigns`

- `custom_points`: Pontos personalizados (NUMERIC)
- `points_per_value`: Pontos por valor gasto (NUMERIC) - Ex: 1 ponto por cada 10 MZN
- `created_by`: ID do usuário que criou a campanha
- `merchant_id`: ID do merchant que criou a campanha (se aplicável)

### Role `merchant`

Adicionada ao sistema de roles com permissões:
- `establishments`: read
- `campaigns`: read, create, update
- `purchases`: read, confirm
- `customers`: read
- `profile`: read, update

## 🔐 Sistema de Permissões

### Permissões de Merchants

1. **can_create_campaigns**: Permite ao merchant criar campanhas
   - Por padrão: `FALSE`
   - Apenas admin pode conceder/revogar

2. **can_set_custom_points**: Permite ao merchant definir pontos personalizados
   - Por padrão: `FALSE`
   - Apenas admin pode conceder/revogar
   - Requer que `can_create_campaigns` seja `TRUE` para usar

### Permissões de Campanhas

- **Admin**: Pode criar, editar e deletar qualquer campanha
- **Merchant**: Pode criar campanhas apenas se tiver `can_create_campaigns = TRUE`
- **Merchant**: Pode editar apenas campanhas que ele criou
- **Merchant**: Pode definir pontos personalizados apenas se tiver `can_set_custom_points = TRUE`
- **Merchant**: Não pode deletar campanhas (apenas admin)

## 📡 API Endpoints

### Merchants

#### Criar Merchant (Admin apenas)
```
POST /api/merchants
Body: {
    "user_id": 1,
    "establishment_id": 5,
    "can_create_campaigns": false,
    "can_set_custom_points": false,
    "is_active": true
}
```

#### Buscar Merchant por ID
```
GET /api/merchants/:id
```

#### Buscar Merchants de um Estabelecimento
```
GET /api/merchants/establishment/:establishmentId?page=1&limit=10&is_active=true
```

#### Buscar Merchants de um Usuário
```
GET /api/merchants/user/:userId?page=1&limit=10&is_active=true
```

#### Buscar Todos os Merchants (Admin)
```
GET /api/merchants?page=1&limit=10&is_active=true
```

#### Atualizar Merchant (Admin)
```
PUT /api/merchants/:id
Body: {
    "can_create_campaigns": true,
    "can_set_custom_points": true,
    "is_active": true
}
```

#### Dar Permissão de Criar Campanhas (Admin)
```
POST /api/merchants/:id/permissions/campaigns/grant
```

#### Remover Permissão de Criar Campanhas (Admin)
```
POST /api/merchants/:id/permissions/campaigns/revoke
```

#### Dar Permissão de Definir Pontos Personalizados (Admin)
```
POST /api/merchants/:id/permissions/custom-points/grant
```

#### Remover Permissão de Definir Pontos Personalizados (Admin)
```
POST /api/merchants/:id/permissions/custom-points/revoke
```

#### Deletar Merchant (Admin)
```
DELETE /api/merchants/:id
```

#### Verificar se Usuário é Merchant
```
GET /api/merchants/check
```

### Campaigns

#### Criar Campanha (Admin ou Merchant com permissão)
```
POST /api/campaigns
Body: {
    "establishment_id": 5,
    "type": "points",
    "description": "Ganhe pontos em todas as compras",
    "conversion_rate": 0.2,
    "min_spend": 50,
    "bonus_multiplier": 1.0,
    "required_visits": null,
    "reward": null,
    "valid_until": "2024-12-31",
    "custom_points": 100,  // Opcional: pontos personalizados
    "points_per_value": 0.1,  // Opcional: 1 ponto por cada 10 MZN
    "active": true
}
```

#### Buscar Campanha por ID
```
GET /api/campaigns/:id
```

#### Buscar Campanhas de um Estabelecimento
```
GET /api/campaigns/establishment/:establishmentId?page=1&limit=10&active=true
```

#### Buscar Todas as Campanhas
```
GET /api/campaigns?page=1&limit=10&active=true
```

#### Atualizar Campanha (Admin ou Merchant que criou)
```
PUT /api/campaigns/:id
Body: {
    "description": "Nova descrição",
    "custom_points": 150,
    "active": true
}
```

#### Deletar Campanha (Admin apenas)
```
DELETE /api/campaigns/:id
```

#### Ativar Campanha
```
POST /api/campaigns/:id/activate
```

#### Desativar Campanha
```
POST /api/campaigns/:id/deactivate
```

## 🔄 Fluxo de Uso

### 1. Admin cria Merchant

```javascript
POST /api/merchants
{
    "user_id": 10,
    "establishment_id": 5,
    "can_create_campaigns": false,
    "can_set_custom_points": false
}
```

### 2. Admin concede permissões

```javascript
// Dar permissão de criar campanhas
POST /api/merchants/1/permissions/campaigns/grant

// Dar permissão de definir pontos personalizados (opcional)
POST /api/merchants/1/permissions/custom-points/grant
```

### 3. Merchant cria campanha

```javascript
POST /api/campaigns
{
    "establishment_id": 5,
    "type": "points",
    "description": "Ganhe 100 pontos em compras acima de 100 MZN",
    "min_spend": 100,
    "custom_points": 100,  // Se tiver permissão
    "active": true
}
```

### 4. Clientes consomem e ganham pontos

Quando um cliente faz uma compra no estabelecimento, o sistema:
1. Verifica se existe uma campanha ativa
2. Aplica as regras da campanha (min_spend, required_visits, etc.)
3. Calcula pontos usando:
   - `custom_points` (se definido)
   - `points_per_value` (se definido)
   - `conversion_rate` (padrão: 20%)

## 📝 Arquivos Criados

1. **`create-merchants-system.js`**: Script para criar tabela merchants e atualizar campaigns
2. **`models/MerchantsModel.js`**: Modelo para gerenciar merchants
3. **`models/CampaignsModel.js`**: Modelo para gerenciar campanhas
4. **`controllers/merchantsController.js`**: Controller de merchants
5. **`controllers/campaignsController.js`**: Controller de campanhas
6. **`routes/merchantsRoutes.js`**: Rotas de merchants
7. **`routes/campaignsRoutes.js`**: Rotas de campanhas

## 🚀 Próximos Passos

1. Executar `create-merchants-system.js` para criar a estrutura no banco
2. Atualizar `purchaseController.js` para usar pontos personalizados das campanhas
3. Testar endpoints de merchants e campaigns
4. Criar interface de admin para gerenciar merchants

## 📌 Notas Importantes

- Apenas admin pode criar merchants e conceder permissões
- Merchants só podem editar campanhas que eles criaram
- Para definir pontos personalizados, o merchant precisa de permissão explícita
- O sistema mantém histórico de quem criou cada campanha (`created_by` e `merchant_id`)