# 🏪 Conceito Proposto: Merchant = Loja + Merchant Users/Owners

## ✅ **Estrutura Proposta (Recomendada)**

### **Conceito:**

1. **Merchant** = A loja física (entidade comercial)
   - Campos: `name`, `type`, `address`, `phone`, `qr_code`, etc.
   - `owner_id` = Usuário principal/dono da loja

2. **Merchant Users/Owners** = Usuários que podem gerenciar essa loja específica
   - Tabela: `merchant_users` (ou manter `merchants` mas com conceito diferente)
   - Campos: `user_id`, `merchant_id`, `can_create_campaigns`, `can_manage_merchant`, etc.
   - Quando fazem login, veem apenas dados da sua loja

---

## 🗄️ **Estrutura do Banco de Dados Proposta**

### **1. Tabela `merchants` (Loja)**

```sql
CREATE TABLE merchants (
    merchant_id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,              -- Nome da loja
    type VARCHAR(50),                        -- Tipo de loja
    address TEXT,
    phone VARCHAR(50),
    email VARCHAR(120),
    qr_code VARCHAR(100) UNIQUE,
    owner_id INTEGER REFERENCES users(user_id),  -- Dono principal
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

**Responsabilidades:**
- ✅ Representa a loja física
- ✅ Armazena informações da loja (nome, endereço, QR code, etc.)
- ✅ `owner_id` = Dono principal da loja

---

### **2. Tabela `merchant_users` (Usuários da Loja)**

```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,      -- Pode criar campanhas
    can_manage_merchant BOOLEAN DEFAULT FALSE,       -- Pode gerenciar a loja
    can_manage_users BOOLEAN DEFAULT FALSE,          -- Pode gerenciar usuários da loja
    can_view_reports BOOLEAN DEFAULT TRUE,           -- Pode ver relatórios
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by INTEGER REFERENCES users(user_id),
    UNIQUE(merchant_id, user_id)
);
```

**Responsabilidades:**
- ✅ Relaciona usuários com lojas específicas
- ✅ Define permissões por loja
- ✅ Permite múltiplos usuários gerenciarem uma loja
- ✅ Permite um usuário gerenciar múltiplas lojas

---

### **3. Atualizar Tabelas Relacionadas**

```sql
-- Tabela campaigns (campanhas da loja)
CREATE TABLE campaigns (
    campaign_id VARCHAR(64) PRIMARY KEY,
    merchant_id VARCHAR(64) REFERENCES merchants(merchant_id),  -- Referência à loja
    created_by INTEGER REFERENCES users(user_id),  -- Usuário que criou
    ...
);

-- Tabela purchases (compras na loja)
CREATE TABLE purchases (
    purchase_id VARCHAR(64) PRIMARY KEY,
    merchant_id VARCHAR(64) REFERENCES merchants(merchant_id),  -- Referência à loja
    ...
);
```

---

## 🔐 **Sistema de Permissões**

### **Permissões por Loja:**

1. **can_create_campaigns**: Pode criar campanhas para esta loja
2. **can_manage_merchant**: Pode editar informações da loja
3. **can_manage_users**: Pode adicionar/remover usuários da loja
4. **can_view_reports**: Pode ver relatórios da loja

### **Como Funciona:**

- Quando um usuário faz login, o sistema verifica em `merchant_users` quais lojas ele pode gerenciar
- Usuário só vê dados das lojas que ele tem permissão
- Admin pode ver todas as lojas

---

## 📡 **API Endpoints Propostos**

### **Merchants (Lojas)**

```http
GET /api/merchants                    # Listar todas as lojas (admin) ou apenas minhas (merchant user)
GET /api/merchants/:id                # Buscar loja por ID
POST /api/merchants                   # Criar loja (admin)
PUT /api/merchants/:id                # Atualizar loja (admin ou merchant user com can_manage_merchant)
DELETE /api/merchants/:id             # Deletar loja (admin)
```

### **Merchant Users (Usuários da Loja)**

```http
GET /api/merchants/:id/users           # Listar usuários de uma loja
POST /api/merchants/:id/users          # Adicionar usuário à loja (admin ou can_manage_users)
PUT /api/merchants/:id/users/:userId   # Atualizar permissões do usuário (admin ou can_manage_users)
DELETE /api/merchants/:id/users/:userId # Remover usuário da loja (admin ou can_manage_users)
GET /api/merchants/my-merchants        # Listar minhas lojas (usuário logado)
```

### **Campanhas**

```http
GET /api/campaigns                     # Listar campanhas (admin vê todas, merchant user vê apenas das suas lojas)
GET /api/campaigns/merchant/:merchantId # Listar campanhas de uma loja específica
POST /api/campaigns                    # Criar campanha (admin ou merchant user com can_create_campaigns)
PUT /api/campaigns/:id                 # Atualizar campanha (admin ou quem criou)
DELETE /api/campaigns/:id              # Deletar campanha (admin)
```

---

## 🔄 **Fluxo de Uso Proposto**

### **1. Admin cria Merchant (Loja)**

```javascript
POST /api/merchants
{
    "name": "Loja Exemplo",
    "type": "Restaurante",
    "address": "Rua Exemplo, 123",
    "phone": "+258841234567",
    "email": "loja@exemplo.com",
    "qr_code": "QR_123456",
    "owner_id": 10  // Dono principal
}
```

### **2. Admin adiciona usuários à loja**

```javascript
POST /api/merchants/1/users
{
    "user_id": 15,
    "can_create_campaigns": true,
    "can_manage_merchant": false,
    "can_manage_users": false,
    "can_view_reports": true
}
```

### **3. Merchant User faz login**

```javascript
POST /api/auth/signin
{
    "username": "usuario.loja",
    "password": "senha123"
}

// Resposta inclui:
{
    "user": {...},
    "merchants": [
        {
            "merchant_id": 1,
            "name": "Loja Exemplo",
            "permissions": {
                "can_create_campaigns": true,
                "can_manage_merchant": false,
                "can_manage_users": false,
                "can_view_reports": true
            }
        }
    ]
}
```

### **4. Merchant User cria campanha (apenas para sua loja)**

```javascript
POST /api/campaigns
{
    "merchant_id": 1,  // Sua loja
    "type": "points",
    "description": "Ganhe pontos em todas as compras",
    ...
}
```

### **5. Merchant User vê apenas dados da sua loja**

```javascript
GET /api/merchants/my-merchants  // Retorna apenas lojas que ele gerencia
GET /api/campaigns               // Retorna apenas campanhas das suas lojas
GET /api/purchases               // Retorna apenas compras das suas lojas
```

---

## ✅ **Benefícios desta Estrutura**

1. ✅ **Clareza Conceitual**: Merchant = Loja (entidade física)
2. ✅ **Múltiplos Usuários**: Uma loja pode ter vários usuários gerenciando
3. ✅ **Permissões Granulares**: Permissões por loja, não globais
4. ✅ **Isolamento de Dados**: Usuário só vê dados das suas lojas
5. ✅ **Flexibilidade**: Um usuário pode gerenciar múltiplas lojas
6. ✅ **Escalabilidade**: Fácil adicionar novas lojas e usuários

---

## 🔄 **Migração Necessária**

### **1. Renomear `establishments` → `merchants`**

```sql
ALTER TABLE establishments RENAME TO merchants;
ALTER TABLE merchants RENAME COLUMN establishment_id TO merchant_id;
ALTER TABLE merchants RENAME COLUMN created_by TO owner_id;
```

### **2. Criar 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)
);
```

### **3. Migrar dados da tabela `merchants` antiga**

```sql
-- Migrar relacionamentos antigos para merchant_users
INSERT INTO merchant_users (merchant_id, user_id, can_create_campaigns, can_manage_merchant, created_by)
SELECT establishment_id, user_id, can_create_campaigns, true, created_by
FROM merchants  -- Tabela antiga
WHERE user_id IS NOT NULL AND establishment_id IS NOT NULL;
```

### **4. Atualizar referências**

```sql
-- Atualizar campaigns
ALTER TABLE campaigns RENAME COLUMN est_id TO merchant_id;
ALTER TABLE campaigns RENAME COLUMN establishment_id TO merchant_id;

-- Atualizar purchases
ALTER TABLE purchases RENAME COLUMN establishment_id TO merchant_id;
```

---

## 📝 **Resumo da Estrutura**

### **Antes (Confuso):**
- `establishments` = Loja
- `merchants` = Relação usuário ↔ estabelecimento (redundante)
- Identificação implícita via `establishments.created_by`

### **Depois (Claro):**
- `merchants` = Loja física
- `merchant_users` = Usuários que gerenciam a loja (com permissões)
- `merchants.owner_id` = Dono principal da loja

---

## ✅ **Conclusão**

Esta estrutura é **muito melhor** porque:
- ✅ Elimina confusão conceitual
- ✅ Permite múltiplos usuários por loja
- ✅ Permissões granulares por loja
- ✅ Isolamento de dados (usuário só vê suas lojas)
- ✅ Terminologia padrão (merchant = loja)

**Próximo Passo:** Implementar esta estrutura!