# 🔗 Relacionamento Usuário ↔ Loja (Múltiplas Lojas / Múltiplos Usuários)

## ✅ **Estrutura Implementada**

A estrutura permite:
- ✅ **Um usuário pode ter várias lojas** (múltiplas lojas)
- ✅ **Uma loja pode ter vários usuários** (múltiplos usuários)
- ✅ **Operações em lote** (bulk operations) para facilitar relacionamentos

---

## 📊 **Estrutura do Banco de Dados**

### **Tabela `merchant_users`**

```sql
CREATE TABLE merchant_users (
    merchant_user_id SERIAL PRIMARY KEY,
    merchant_id INTEGER NOT NULL REFERENCES merchants(merchant_id) ON DELETE CASCADE,
    user_id INTEGER NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
    can_create_campaigns BOOLEAN DEFAULT FALSE,
    can_manage_merchant BOOLEAN DEFAULT FALSE,
    can_manage_users BOOLEAN DEFAULT FALSE,
    can_view_reports BOOLEAN DEFAULT TRUE,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by INTEGER REFERENCES users(user_id),
    UNIQUE(merchant_id, user_id)  -- Garante que um usuário não seja adicionado duas vezes à mesma loja
);
```

**Características:**
- `UNIQUE(merchant_id, user_id)` garante que um usuário não seja relacionado duas vezes à mesma loja
- Um usuário pode ter múltiplas linhas (uma para cada loja)
- Uma loja pode ter múltiplas linhas (uma para cada usuário)

---

## 🔄 **Operações Disponíveis**

### **1. Operações Individuais**

#### **Adicionar usuário a uma loja**
```http
POST /api/merchants/:id/users
{
    "user_id": 15,
    "can_create_campaigns": true,
    "can_manage_merchant": false,
    "can_manage_users": false,
    "can_view_reports": true
}
```

#### **Remover usuário de uma loja**
```http
DELETE /api/merchants/:id/users/:userId
```

#### **Atualizar permissões do usuário**
```http
PUT /api/merchants/:id/users/:userId
{
    "can_create_campaigns": true,
    "can_manage_merchant": true
}
```

---

### **2. Operações em Lote (Bulk)**

#### **Adicionar usuário a múltiplas lojas**
```http
POST /api/merchants/users/bulk
{
    "user_id": 15,
    "merchant_ids": [1, 2, 3, 4, 5],
    "permissions": {
        "can_create_campaigns": true,
        "can_manage_merchant": false,
        "can_manage_users": false,
        "can_view_reports": true
    }
}

// Resposta:
{
    "success": true,
    "message": "5 relacionamento(s) criado(s) com sucesso",
    "data": [
        { "success": true, "merchant_id": 1, "data": {...} },
        { "success": true, "merchant_id": 2, "data": {...} },
        ...
    ],
    "summary": {
        "total": 5,
        "success": 5,
        "failed": 0
    }
}
```

#### **Adicionar múltiplos usuários a uma loja**
```http
POST /api/merchants/:id/users/bulk
{
    "user_ids": [10, 15, 20, 25],
    "permissions": {
        "can_create_campaigns": true,
        "can_manage_merchant": false,
        "can_manage_users": false,
        "can_view_reports": true
    }
}

// Resposta:
{
    "success": true,
    "message": "4 usuário(s) adicionado(s) com sucesso",
    "data": [
        { "success": true, "user_id": 10, "data": {...} },
        { "success": true, "user_id": 15, "data": {...} },
        ...
    ],
    "summary": {
        "total": 4,
        "success": 4,
        "failed": 0
    }
}
```

#### **Remover usuário de múltiplas lojas**
```http
DELETE /api/merchants/users/bulk
{
    "user_id": 15,
    "merchant_ids": [1, 2, 3]
}

// Resposta:
{
    "success": true,
    "message": "3 relacionamento(s) removido(s) com sucesso",
    "data": [...]
}
```

#### **Remover múltiplos usuários de uma loja**
```http
DELETE /api/merchants/:id/users/bulk
{
    "user_ids": [10, 15, 20]
}

// Resposta:
{
    "success": true,
    "message": "3 usuário(s) removido(s) com sucesso",
    "data": [...]
}
```

---

## 📋 **Consultas Disponíveis**

### **Listar lojas do usuário logado**
```http
GET /api/merchants/my-merchants

// Resposta:
{
    "success": true,
    "data": [
        {
            "merchant_id": 1,
            "merchant_name": "Loja Exemplo 1",
            "merchant_type": "Restaurante",
            "qr_code": "QR_123456",
            "can_create_campaigns": true,
            "can_manage_merchant": false,
            "can_manage_users": false,
            "can_view_reports": true
        },
        {
            "merchant_id": 2,
            "merchant_name": "Loja Exemplo 2",
            "merchant_type": "Supermercado",
            "qr_code": "QR_789012",
            "can_create_campaigns": true,
            "can_manage_merchant": true,
            "can_manage_users": true,
            "can_view_reports": true
        }
    ]
}
```

### **Listar usuários de uma loja**
```http
GET /api/merchants/:id/users

// Resposta:
{
    "success": true,
    "data": [
        {
            "merchant_user_id": 1,
            "merchant_id": 1,
            "user_id": 10,
            "username": "usuario1",
            "email": "usuario1@exemplo.com",
            "first_name": "João",
            "last_name": "Silva",
            "can_create_campaigns": true,
            "can_manage_merchant": false,
            "can_manage_users": false,
            "can_view_reports": true
        },
        ...
    ]
}
```

---

## 🔐 **Permissões**

### **Permissões por Loja:**
- `can_create_campaigns` - Pode criar campanhas para esta loja
- `can_manage_merchant` - Pode editar informações da loja
- `can_manage_users` - Pode adicionar/remover usuários da loja
- `can_view_reports` - Pode ver relatórios da loja

### **Regras de Permissão:**
1. **Admin** tem todas as permissões para todas as lojas
2. **Owner** (dono principal) tem todas as permissões para sua loja
3. **Merchant Users** têm permissões específicas definidas em `merchant_users`

---

## 🔄 **Fluxo de Uso**

### **Cenário 1: Usuário com múltiplas lojas**

1. **Admin adiciona usuário a múltiplas lojas:**
```javascript
POST /api/merchants/users/bulk
{
    "user_id": 15,
    "merchant_ids": [1, 2, 3],
    "permissions": {
        "can_create_campaigns": true,
        "can_view_reports": true
    }
}
```

2. **Usuário faz login e recebe todas as suas lojas:**
```javascript
POST /api/auth/login
{
    "username": "usuario.lojas",
    "password": "senha123"
}

// Resposta inclui:
{
    "user": {
        ...
        "merchants": [
            { "merchant_id": 1, "merchant_name": "Loja 1", ... },
            { "merchant_id": 2, "merchant_name": "Loja 2", ... },
            { "merchant_id": 3, "merchant_name": "Loja 3", ... }
        ]
    }
}
```

3. **Usuário vê apenas dados das suas lojas:**
- Ao listar campanhas: só vê campanhas das lojas 1, 2, 3
- Ao listar compras: só vê compras das lojas 1, 2, 3
- Ao criar campanha: só pode criar para lojas 1, 2, 3

---

### **Cenário 2: Loja com múltiplos usuários**

1. **Admin adiciona múltiplos usuários a uma loja:**
```javascript
POST /api/merchants/1/users/bulk
{
    "user_ids": [10, 15, 20],
    "permissions": {
        "can_create_campaigns": true,
        "can_view_reports": true
    }
}
```

2. **Todos os usuários podem gerenciar a loja:**
- Usuário 10 pode criar campanhas para loja 1
- Usuário 15 pode criar campanhas para loja 1
- Usuário 20 pode criar campanhas para loja 1

3. **Cada usuário vê apenas suas lojas ao fazer login:**
- Usuário 10 vê loja 1 (e outras lojas que ele gerencia)
- Usuário 15 vê loja 1 (e outras lojas que ele gerencia)
- Usuário 20 vê loja 1 (e outras lojas que ele gerencia)

---

## ✅ **Benefícios**

1. ✅ **Flexibilidade**: Um usuário pode gerenciar múltiplas lojas
2. ✅ **Colaboração**: Múltiplos usuários podem gerenciar uma loja
3. ✅ **Permissões Granulares**: Permissões por loja, não globais
4. ✅ **Operações em Lote**: Facilita adicionar/remover múltiplos relacionamentos
5. ✅ **Isolamento de Dados**: Cada usuário vê apenas suas lojas
6. ✅ **Escalabilidade**: Fácil adicionar novas lojas e usuários

---

## 📝 **Exemplos de Uso**

### **Exemplo 1: Gerente de múltiplas lojas**
```javascript
// Admin adiciona gerente a 5 lojas
POST /api/merchants/users/bulk
{
    "user_id": 50,  // Gerente
    "merchant_ids": [1, 2, 3, 4, 5],
    "permissions": {
        "can_create_campaigns": true,
        "can_manage_merchant": true,
        "can_manage_users": true,
        "can_view_reports": true
    }
}
```

### **Exemplo 2: Equipe de uma loja**
```javascript
// Admin adiciona equipe à loja
POST /api/merchants/1/users/bulk
{
    "user_ids": [10, 11, 12, 13, 14],  // Equipe
    "permissions": {
        "can_create_campaigns": true,
        "can_view_reports": true
    }
}
```

### **Exemplo 3: Remover usuário de todas as lojas**
```javascript
// Admin remove usuário de todas as lojas
DELETE /api/merchants/users/bulk
{
    "user_id": 15,
    "merchant_ids": [1, 2, 3, 4, 5]
}
```

---

## ✅ **Conclusão**

A estrutura permite relacionar usuários e lojas de forma flexível:
- ✅ Um usuário pode ter várias lojas
- ✅ Uma loja pode ter vários usuários
- ✅ Operações em lote facilitam gerenciamento
- ✅ Permissões granulares por loja
- ✅ Isolamento de dados por usuário

**Status:** ✅ Implementação completa e funcional!