# Sistema de Afiliados - Checkout Pro 2025

## 📋 Visão Geral

O sistema de afiliados permite que usuários se tornem afiliados de produtos e ganhem comissões sobre vendas geradas através de seus links de divulgação. Similar ao modelo Kiwify/Hotmart, mantém o fluxo de pagamento na conta do admin, mas registra informações de produtor e afiliado para relatórios futuros.

---

## 🗄️ Estrutura das Tabelas

### Tabela `afiliacoes`

Relacionamento entre produtos e afiliados.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | INT(11) | Chave primária, auto-incremento |
| `produto_id` | INT(11) | ID do produto (FK para `produtos`) |
| `usuario_id` | INT(11) | ID do usuário afiliado (FK para `usuarios`) |
| `comissao_tipo` | VARCHAR(20) | Tipo: 'percentual' ou 'fixo' |
| `comissao_valor` | DECIMAL(10,2) | Valor da comissão |
| `status` | VARCHAR(20) | Status: 'ativo', 'inativo', 'pendente' |
| `created_at` | DATETIME | Data de criação |
| `updated_at` | DATETIME | Data de atualização |

**Índices:**
- PRIMARY KEY: `id`
- UNIQUE: `produto_id` + `usuario_id` (um usuário só pode ser afiliado uma vez por produto)
- KEY: `idx_produto_id`, `idx_usuario_id`, `idx_status`

### Tabela `produtos` (Campos Adicionados)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `afiliacao_ativa` | TINYINT(1) | 1 = aceita afiliados, 0 = não aceita |
| `comissao_padrao` | DECIMAL(10,2) | Comissão padrão para afiliados (percentual) |

### Tabela `transacoes` (Campos Adicionados)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `produtor_id` | INT(11) | ID do usuário produtor (dono do produto) |
| `afiliado_id` | INT(11) | ID do usuário afiliado (se houver) |

---

## 🔄 Migrações SQL

### 1. Tabela de Afiliações

**Arquivo**: `config/sql_migrations/2025_04_afiliados.sql`

Cria a tabela `afiliacoes` com todos os campos necessários.

### 2. Campos de Afiliação em Produtos

**Arquivo**: `config/sql_migrations/2025_05_add_afiliacao_campos_produtos.sql`

Adiciona `afiliacao_ativa` e `comissao_padrao` na tabela `produtos`.

### 3. Campos de Produtor e Afiliado em Transações

**Arquivo**: `config/sql_migrations/2025_06_add_produtor_afiliado_transacoes.sql`

Adiciona `produtor_id` e `afiliado_id` na tabela `transacoes`.

### Como Executar

1. Execute as migrações na ordem:
   ```sql
   -- 1. Criar tabela de afiliações
   -- Execute: config/sql_migrations/2025_04_afiliados.sql
   
   -- 2. Adicionar campos em produtos
   -- Execute: config/sql_migrations/2025_05_add_afiliacao_campos_produtos.sql
   
   -- 3. Adicionar campos em transações
   -- Execute: config/sql_migrations/2025_06_add_produtor_afiliado_transacoes.sql
   ```

2. Verifique a migração:
   ```sql
   SELECT COUNT(*) FROM afiliacoes;
   SELECT COUNT(*) FROM produtos WHERE afiliacao_ativa = 1;
   SELECT COUNT(*) FROM transacoes WHERE produtor_id IS NOT NULL;
   ```

---

## ✅ Como Habilitar Afiliação em um Produto

### Para Administradores

1. Acesse o **Dashboard Admin** → **Produtos**
2. Crie um novo produto ou edite um existente
3. No formulário, marque o checkbox **"Permitir afiliação para este produto"**
4. Defina a **Comissão Padrão (%)** (ex: 50.00 = 50%)
5. Salve o produto

### Para Usuários Comuns

1. Acesse a **Área do Usuário** → **Meus Produtos**
2. Crie um novo produto ou edite um existente
3. No formulário, marque o checkbox **"Permitir afiliação para este produto"**
4. Defina a **Comissão Padrão (%)**
5. Salve o produto

### Via SQL (Avançado)

```sql
-- Habilitar afiliação em um produto
UPDATE produtos 
SET afiliacao_ativa = 1, comissao_padrao = 50.00 
WHERE id = X;
```

---

## 👥 Como Tornar-se Afiliado

### Processo

1. Acesse a **Área do Usuário** → **Afiliação Marketplace**
2. Visualize produtos que aceitam afiliação
3. Clique em **"Quero ser afiliado"** no produto desejado
4. O sistema cria automaticamente a afiliação com status 'ativo'
5. Você recebe um link de afiliado único

### Link de Afiliado

O link de afiliado é gerado automaticamente no formato:

```
https://seusite.com/views/dados_pessoais.php?produto_id=X&af=ID_AFILIACAO
```

Onde:
- `produto_id`: ID do produto
- `af`: ID da afiliação (não o ID do usuário, mas o ID do registro em `afiliacoes`)

### Exemplo

Se você se tornou afiliado do produto ID 5, e sua afiliação tem ID 10:

```
https://seusite.com/views/dados_pessoais.php?produto_id=5&af=10
```

---

## 🔗 Fluxo de Captura do Afiliado

### 1. Entrada no Sistema

Quando um visitante acessa `dados_pessoais.php?produto_id=X&af=ID_AFILIACAO`:

1. O sistema valida se o afiliado existe e está ativo
2. Se válido, salva em **cookie** (`affiliate_id` e `affiliate_produto_id`)
3. Cookie válido por **30 dias**

### 2. Durante o Checkout

O sistema verifica o cookie e mantém a referência do afiliado durante todo o fluxo.

### 3. No Processamento do Pagamento

Quando a transação é processada (`process_payment.php` ou `process_payment_pix.php`):

1. Busca o `produto_id` dos dados da transação
2. Busca o `usuario_id` do produto (produtor)
3. Valida o cookie de afiliado
4. Registra na transação:
   - `produtor_id`: ID do dono do produto
   - `afiliado_id`: ID do afiliado (se houver)

---

## 📊 Regras de Exibição

### Produtos que Aceitam Afiliação

Um produto aceita afiliação se:

1. ✅ `afiliacao_ativa = 1`
2. ✅ `status_produto = 'ativo'` (ou NULL/vazio)
3. ✅ `is_marketplace = 1` (para aparecer na página de afiliação)

### Afiliados Válidos

Um afiliado é válido se:

1. ✅ Existe registro em `afiliacoes`
2. ✅ `status = 'ativo'`
3. ✅ `produto_id` corresponde ao produto
4. ✅ `usuario_id` corresponde a um usuário válido

### Restrições

- ❌ Um usuário **não pode** ser afiliado do seu próprio produto
- ❌ Um usuário só pode ter **uma afiliação** por produto (UNIQUE constraint)
- ❌ Afiliados inativos não geram comissões

---

## 📈 Relatórios

### Dashboard Admin

**Página**: `dashboard/pages/pedidos.php`

Exibe:
- Nome do **produtor** (se houver)
- Nome do **afiliado** (se houver)
- Todas as outras informações da transação

### Área do Usuário - Vendas como Afiliado

**Página**: `dashboard/pages_usuario/minhas_vendas_afiliado.php`

Lista vendas onde `transacoes.afiliado_id = usuario_logado().id`

Exibe:
- Data da venda
- Produto vendido
- Cliente
- Produtor
- Valor
- Status

**Estatísticas:**
- Total de vendas
- Vendas aprovadas
- Valor total aprovado

### Área do Usuário - Vendas como Produtor

**Página**: `dashboard/pages_usuario/minhas_vendas_produtor.php`

Lista vendas onde `transacoes.produtor_id = usuario_logado().id`

Exibe:
- Data da venda
- Produto vendido
- Cliente
- Afiliado (se houver)
- Valor
- Status

**Estatísticas:**
- Total de vendas
- Vendas aprovadas
- Valor total aprovado

---

## 🔧 Implementação Técnica

### Criação de Afiliação

```php
// Quando usuário clica em "Quero ser afiliado"
INSERT INTO afiliacoes (produto_id, usuario_id, comissao_tipo, comissao_valor, status, created_at, updated_at) 
VALUES (:produto_id, :usuario_id, 'percentual', :comissao_padrao, 'ativo', NOW(), NOW());
```

### Captura do Afiliado

```php
// Em dados_pessoais.php
if (isset($_GET['af'])) {
    $afiliado_id = intval($_GET['af']);
    // Validar afiliado
    // Salvar em cookie
    setcookie('affiliate_id', $afiliado_id, time() + (30 * 24 * 60 * 60), '/');
    setcookie('affiliate_produto_id', $produto_id, time() + (30 * 24 * 60 * 60), '/');
}
```

### Registro na Transação

```php
// Em process_payment.php ou process_payment_pix.php
$produto_id = $data['product']['id'];
$produtor_id = buscar_produtor_id($produto_id);
$afiliado_id = validar_cookie_afiliado($produto_id);

INSERT INTO transacoes (produto_id, produtor_id, afiliado_id, ...) 
VALUES (:produto_id, :produtor_id, :afiliado_id, ...);
```

---

## 🔄 Retrocompatibilidade

### Transações Sem Campos de Afiliado

- Se as colunas `produtor_id` e `afiliado_id` não existirem, o sistema funciona normalmente
- As queries incluem tratamento de erro para retrocompatibilidade
- Transações antigas não terão essas informações, mas não quebram o sistema

### Produtos Sem Campos de Afiliação

- Se `afiliacao_ativa` e `comissao_padrao` não existirem, produtos não aceitam afiliação
- O sistema trata como `afiliacao_ativa = 0` por padrão

---

## 📊 Consultas Úteis

### Verificar Afiliações

```sql
-- Todas as afiliações ativas
SELECT a.id, p.nome as produto, u.nome as afiliado, a.comissao_valor, a.status
FROM afiliacoes a
INNER JOIN produtos p ON p.id = a.produto_id
INNER JOIN usuarios u ON u.id = a.usuario_id
WHERE a.status = 'ativo';

-- Afiliações por produto
SELECT p.nome, COUNT(a.id) as total_afiliados
FROM produtos p
LEFT JOIN afiliacoes a ON a.produto_id = p.id AND a.status = 'ativo'
WHERE p.afiliacao_ativa = 1
GROUP BY p.id, p.nome;
```

### Vendas com Afiliado

```sql
-- Vendas geradas por afiliados
SELECT u.nome as afiliado, COUNT(t.id) as total_vendas, SUM(t.valor) as total_valor
FROM transacoes t
INNER JOIN usuarios u ON u.id = t.afiliado_id
WHERE t.afiliado_id IS NOT NULL AND t.status = 'Aprovado'
GROUP BY u.id, u.nome
ORDER BY total_valor DESC;
```

### Vendas por Produtor

```sql
-- Vendas de cada produtor
SELECT u.nome as produtor, COUNT(t.id) as total_vendas, SUM(t.valor) as total_valor
FROM transacoes t
INNER JOIN usuarios u ON u.id = t.produtor_id
WHERE t.produtor_id IS NOT NULL AND t.status = 'Aprovado'
GROUP BY u.id, u.nome
ORDER BY total_valor DESC;
```

---

## 🚀 Próximos Passos

1. **Executar migrações SQL**: Execute as 3 migrações na ordem
2. **Habilitar afiliação**: Marque produtos para aceitar afiliados
3. **Tornar-se afiliado**: Acesse a página de afiliação e se torne afiliado
4. **Testar fluxo**: Use um link de afiliado e complete uma venda
5. **Verificar relatórios**: Confirme que as informações aparecem corretamente

---

## ⚠️ Notas Importantes

- ⚠️ **Fluxo de Pagamento**: O pagamento continua sendo processado na conta do admin
- ⚠️ **Comissões**: O sistema registra as informações, mas **não calcula saldos ainda**
- ⚠️ **Cookies**: Afiliados são rastreados via cookies (válidos por 30 dias)
- ⚠️ **Validação**: O sistema valida afiliados antes de registrar na transação
- ⚠️ **Retrocompatibilidade**: Funciona mesmo sem as novas colunas

---

## 🆘 Suporte

Em caso de dúvidas ou problemas:

1. Verifique se as migrações SQL foram executadas
2. Confirme que os produtos têm `afiliacao_ativa = 1`
3. Verifique se as afiliações estão com `status = 'ativo'`
4. Confirme que os cookies estão sendo salvos corretamente
5. Verifique os logs de erro do PHP

---

**Última atualização**: Janeiro 2025  
**Versão do sistema**: Checkout Pro 2025


