# 📋 Como Alocar Usuários para Gerenciar Estabelecimentos

## 🎯 Endpoint

**POST** `/api/merchants/establishments/:establishmentId/allocate`

**Autenticação:** Requer autenticação e permissão de **admin**

---

## 📝 Descrição

Este endpoint permite alocar usuários (com role "admin" ou "merchant") a um estabelecimento para que possam gerenciá-lo e criar campanhas.

---

## 🔧 Parâmetros

### Path Parameters
- `establishmentId` (obrigatório): ID do estabelecimento

### Body Parameters
```json
{
  "user_id": 123,                    // ID do usuário a ser alocado (obrigatório)
  "can_create_campaigns": true,      // Permissão para criar campanhas (padrão: true)
  "can_manage_merchant": false,      // Permissão para gerenciar o merchant (padrão: false)
  "can_manage_users": false,         // Permissão para gerenciar usuários (padrão: false)
  "can_view_reports": true           // Permissão para ver relatórios (padrão: true)
}
```

---

## ✅ Validações

1. **Estabelecimento deve existir**
2. **Usuário deve existir**
3. **Usuário deve ter role "admin" ou "merchant"** (usuários com role "user" não podem ser alocados)
4. Se o merchant já estiver alocado, as permissões serão atualizadas

---

## 📤 Resposta de Sucesso

### Status: 201 Created (novo alocamento) ou 200 OK (atualização)

```json
{
  "success": true,
  "data": {
    "merchant_user_id": 1,
    "merchant_id": 128,
    "user_id": 123,
    "can_create_campaigns": true,
    "can_manage_merchant": false,
    "can_manage_users": false,
    "can_view_reports": true,
    "is_active": true,
    "created_at": "2025-11-07T23:06:54.167Z",
    "created_by": 2
  },
  "message": "Merchant alocado ao estabelecimento com sucesso"
}
```

---

## ❌ Respostas de Erro

### 400 Bad Request - user_id obrigatório
```json
{
  "success": false,
  "error": "user_id é obrigatório"
}
```

### 404 Not Found - Estabelecimento não encontrado
```json
{
  "success": false,
  "error": "Estabelecimento não encontrado"
}
```

### 404 Not Found - Usuário não encontrado
```json
{
  "success": false,
  "error": "Usuário não encontrado"
}
```

### 400 Bad Request - Role inválida
```json
{
  "success": false,
  "error": "Apenas usuários com role \"admin\" ou \"merchant\" podem ser alocados a estabelecimentos"
}
```

---

## 📋 Exemplos de Uso

### Exemplo 1: Alocar usuário com permissões padrão

**Request:**
```http
POST /api/merchants/establishments/321/allocate
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 123
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "merchant_user_id": 1,
    "merchant_id": 128,
    "user_id": 123,
    "can_create_campaigns": true,
    "can_manage_merchant": false,
    "can_manage_users": false,
    "can_view_reports": true,
    "is_active": true,
    "created_at": "2025-11-07T23:06:54.167Z"
  },
  "message": "Merchant alocado ao estabelecimento com sucesso"
}
```

### Exemplo 2: Alocar usuário com permissões personalizadas

**Request:**
```http
POST /api/merchants/establishments/321/allocate
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 123,
  "can_create_campaigns": true,
  "can_manage_merchant": true,
  "can_manage_users": true,
  "can_view_reports": true
}
```

### Exemplo 3: Atualizar permissões de usuário já alocado

Se o usuário já estiver alocado ao estabelecimento, as permissões serão atualizadas:

**Request:**
```http
POST /api/merchants/establishments/321/allocate
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 123,
  "can_create_campaigns": false,
  "can_manage_merchant": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "merchant_user_id": 1,
    "merchant_id": 128,
    "user_id": 123,
    "can_create_campaigns": false,
    "can_manage_merchant": true,
    "can_manage_users": false,
    "can_view_reports": true,
    "is_active": true,
    "updated_at": "2025-11-07T23:10:00.000Z"
  },
  "message": "Merchant já estava alocado. Permissões atualizadas."
}
```

---

## 🔍 Verificar Usuários Alocados

Para ver os usuários alocados a um estabelecimento, use:

**GET** `/api/establishments/:id`

A resposta incluirá o campo `allocatedMerchants` com todos os merchants alocados e seus usuários:

```json
{
  "success": true,
  "data": {
    "id": 321,
    "name": "Padaria Alberto",
    "allocatedMerchants": [
      {
        "id": 128,
        "name": "Padaria Alberto",
        "type": "Loja",
        "owner": { ... },
        "users": [
          {
            "id": 123,
            "username": "merchant_user",
            "email": "merchant@example.com",
            "permissions": {
              "canCreateCampaigns": true,
              "canManageMerchant": false,
              "canManageUsers": false,
              "canViewReports": true
            }
          }
        ]
      }
    ]
  }
}
```

---

## 📌 Notas Importantes

1. **Apenas admins podem alocar usuários** - O endpoint requer autenticação e permissão de admin
2. **Usuários com role "user" não podem ser alocados** - Apenas "admin" ou "merchant"
3. **Se o merchant não existir para o establishment, ele será criado automaticamente**
4. **Se o usuário já estiver alocado, as permissões serão atualizadas** (não cria duplicado)
5. **O campo `created_by` será preenchido com o ID do usuário que fez a alocação** (ou o próprio usuário se não houver usuário autenticado)

---

## 🎯 Permissões Explicadas

- **can_create_campaigns**: Permite criar campanhas para o estabelecimento
- **can_manage_merchant**: Permite gerenciar configurações do merchant
- **can_manage_users**: Permite gerenciar outros usuários alocados ao estabelecimento
- **can_view_reports**: Permite visualizar relatórios e métricas do estabelecimento

---

## 🔄 Fluxo Completo

1. Admin faz POST para `/api/merchants/establishments/:establishmentId/allocate` com `user_id`
2. Sistema verifica se establishment existe
3. Sistema verifica se usuário existe e tem role válida
4. Sistema cria ou encontra o merchant para o establishment
5. Sistema cria ou atualiza registro em `merchant_users` com as permissões
6. Usuário agora pode gerenciar o estabelecimento conforme as permissões concedidas