# 🎯 Sistema de Afiliados - Implementação Completa
## ✅ O que foi implementado
### 1. Backend - Database
- ✅ Migration `create_affiliates_table` - Tabela de afiliados
- ✅ Migration `create_affiliate_referrals_table` - Tabela de indicações
- ✅ Migration `create_affiliate_commissions_table` - Tabela de comissões
- ✅ Migration `create_affiliate_payouts_table` - Tabela de pagamentos
- ✅ Migration `add_affiliate_fields_to_users_table` - Campos de referência no usuário
- ✅ Migration `add_affiliate_commission_id_to_payments_table` - Link com pagamentos
- ✅ Migration `add_payout_id_to_affiliate_commissions_table` - Link com payouts
### 2. Backend - Models
- ✅ `Affiliate` - Model completo com métodos auxiliares
- ✅ `AffiliateReferral` - Model de indicações
- ✅ `AffiliateCommission` - Model de comissões
- ✅ `AffiliatePayout` - Model de pagamentos
### 3. Backend - Services
- ✅ `AffiliateService` - Serviço completo com:
- Cálculo de comissões (20%, 15%, 10%, 5%)
- Tracking de referências
- Criação de comissões
- Aprovação automática após 30 dias
### 4. Backend - Controllers
- ✅ `AffiliateController` - Controller do usuário:
- GET `/affiliates` - Obter/ criar conta
- GET `/affiliates/stats` - Estatísticas
- GET `/affiliates/referrals` - Lista de indicações
- GET `/affiliates/commissions` - Lista de comissões
- GET `/affiliates/payouts` - Lista de pagamentos
- PUT `/affiliates/pix` - Atualizar dados PIX
- ✅ `AdminAffiliateController` - Controller admin:
- GET `/admin/affiliates` - Listar afiliados
- GET `/admin/affiliates/stats` - Estatísticas gerais
- GET `/admin/affiliates/pending` - Pendentes de aprovação
- GET `/admin/affiliates/{id}` - Detalhes
- POST `/admin/affiliates/{id}/approve` - Aprovar
- POST `/admin/affiliates/{id}/reject` - Desqualificar
- POST `/admin/affiliates/{id}/payout` - Criar pagamento
- GET `/admin/affiliates/payouts` - Listar pagamentos
- POST `/admin/affiliates/payouts/{id}/paid` - Marcar como pago
### 5. Backend - Integrações
- ✅ Integrado no `AuthController::register` - Tracking de referência no registro
- ✅ Integrado no `WebhookController` - Criação de comissões após pagamento
- ✅ Middleware `TrackAffiliateReferral` - Captura código de referência
### 6. Frontend - Páginas
- ✅ `AffiliatePage.tsx` - Painel do afiliado com:
- Link de referência copiável
- Estatísticas (ganhos, indicações, comissões)
- Gráfico de comissões por mês
- Lista de indicações
- Lista de comissões
- Configuração de PIX
- ✅ `AdminAffiliatesPage.tsx` - Painel admin com:
- Lista de afiliados
- Filtros (todos, pendentes, aprovados, ativos)
- Aprovar/Desqualificar afiliados
- Estatísticas
### 7. Sistema de Comissões
- ✅ **20%** na venda inicial
- ✅ **15%** nas duas primeiras renovações
- ✅ **10%** a partir da 3ª renovação
- ✅ **5%** no nível 2 (preparado, não implementado ainda)
## 📋 Próximos Passos Necessários
### 1. Adicionar Rotas no Backend
Adicionar em `backend/routes/api.php`:
```php
use App\Http\Controllers\Api\AffiliateController;
use App\Http\Controllers\Admin\AdminAffiliateController;
// Dentro do grupo auth:sanctum
Route::prefix('affiliates')->group(function () {
Route::get('/', [AffiliateController::class, 'index']);
Route::get('/stats', [AffiliateController::class, 'stats']);
Route::get('/referrals', [AffiliateController::class, 'referrals']);
Route::get('/commissions', [AffiliateController::class, 'commissions']);
Route::get('/payouts', [AffiliateController::class, 'payouts']);
Route::put('/pix', [AffiliateController::class, 'updatePix']);
});
// Dentro do grupo admin
Route::prefix('admin/affiliates')->group(function () {
Route::get('/', [AdminAffiliateController::class, 'index']);
Route::get('/stats', [AdminAffiliateController::class, 'stats']);
Route::get('/pending', [AdminAffiliateController::class, 'pendingApprovals']);
Route::get('/{id}', [AdminAffiliateController::class, 'show']);
Route::post('/{id}/approve', [AdminAffiliateController::class, 'approve']);
Route::post('/{id}/reject', [AdminAffiliateController::class, 'reject']);
Route::post('/{id}/payout', [AdminAffiliateController::class, 'createPayout']);
Route::get('/payouts', [AdminAffiliateController::class, 'payouts']);
Route::post('/payouts/{payoutId}/paid', [AdminAffiliateController::class, 'markPayoutPaid']);
});
```
### 2. Adicionar Middleware de Tracking
No `bootstrap/app.php`, adicionar:
```php
$middleware->web(append: [
\App\Http\Middleware\TrackAffiliateReferral::class,
]);
```
### 3. Atualizar RegisterPage para Enviar Código
No `frontend/src/pages/RegisterPage.tsx`, adicionar:
```typescript
import { useSearchParams } from 'react-router-dom';
// Dentro do componente
const [searchParams] = useSearchParams();
const referralCode = searchParams.get('ref') || document.cookie.match(/affiliate_ref=([^;]+)/)?.[1];
// No handleSubmit, adicionar referral_code:
await register(name, email, password, passwordConfirmation, referralCode);
```
### 4. Atualizar AuthContext
No `frontend/src/contexts/AuthContext.tsx`, atualizar a função `register`:
```typescript
const register = async (name: string, email: string, password: string, passwordConfirmation: string, referralCode?: string) => {
const response = await api.post('/auth/register', {
name,
email,
password,
password_confirmation: passwordConfirmation,
referral_code: referralCode, // Adicionar este campo
});
// ... resto do código
};
```
### 5. Adicionar Link no Sidebar
No `frontend/src/components/Sidebar.tsx` ou `UserSidebar.tsx`, adicionar:
```tsx
Afiliados
```
No `AdminSidebar.tsx`, adicionar:
```tsx
Gerenciar Afiliados
```
### 6. Executar Migrations
```bash
cd /var/www/gestorstream/backend
php artisan migrate
```
### 7. Criar Job para Aprovar Comissões
Criar comando ou job que executa diariamente:
```php
// Em app/Console/Kernel.php
$schedule->call(function () {
$affiliateService = app(\App\Services\AffiliateService::class);
$affiliateService->approvePendingCommissions();
})->daily();
```
## 🎯 Funcionalidades Implementadas
### Para o Afiliado:
1. ✅ Criar conta de afiliado
2. ✅ Obter link único de referência
3. ✅ Ver estatísticas (ganhos, indicações, comissões)
4. ✅ Ver gráfico de comissões por mês
5. ✅ Ver lista de indicações
6. ✅ Ver lista de comissões com status
7. ✅ Configurar dados PIX para recebimento
8. ✅ Comissões aprovadas automaticamente após 30 dias
### Para o Admin:
1. ✅ Listar todos os afiliados
2. ✅ Filtrar por status (pendente, aprovado, ativo)
3. ✅ Aprovar afiliados
4. ✅ Desqualificar afiliados (com motivo)
5. ✅ Ver detalhes completos do afiliado
6. ✅ Criar pagamentos (payouts)
7. ✅ Marcar pagamentos como realizados
8. ✅ Ver estatísticas gerais
## 🔄 Fluxo Completo
1. **Usuário se torna afiliado**:
- Acessa `/affiliate`
- Sistema cria conta automaticamente (status: pendente)
- Admin aprova ou rejeita
2. **Afiliado compartilha link**:
- Copia link único: `https://gestor.jf.eng.br/register?ref=CODIGO123`
- Compartilha em redes sociais, site, etc.
3. **Novo usuário clica no link**:
- Middleware captura código `ref` e salva em cookie/sessão
- Usuário se registra
- Sistema cria `AffiliateReferral` vinculando o novo usuário ao afiliado
4. **Novo usuário faz primeiro pagamento**:
- Webhook recebe confirmação de pagamento
- Sistema cria comissão de **20%** (venda inicial)
- Status: `pending` → após 30 dias → `approved`
5. **Usuário renova assinatura**:
- Webhook recebe confirmação de renovação
- Sistema verifica número da renovação:
- 1ª e 2ª renovação: **15%**
- 3ª+ renovação: **10%**
- Cria comissão com status `pending`
6. **Comissão aprovada após 30 dias**:
- Job diário aprova comissões pendentes há 30+ dias
- Status muda para `approved`
- Fica disponível para pagamento
7. **Admin cria pagamento**:
- Seleciona comissões aprovadas do afiliado
- Cria `AffiliatePayout` com dados PIX
- Status: `pending`
8. **Admin processa pagamento PIX**:
- Realiza transferência PIX manualmente
- Marca payout como `paid`
- Todas as comissões vinculadas são marcadas como `paid`
- Estatísticas do afiliado são atualizadas
## 📊 Estrutura de Dados
### Affiliate
- `user_id` - Usuário dono da conta
- `code` - Código único (8 caracteres)
- `pix_key`, `pix_key_type`, `pix_name` - Dados PIX
- `approved` - Aprovado pelo admin
- `total_earnings`, `paid_earnings`, `pending_earnings` - Estatísticas
### AffiliateReferral
- `affiliate_id` - Afiliado que indicou
- `referred_user_id` - Usuário indicado
- `referral_code` - Código usado
- `converted_at` - Quando se tornou cliente (pagou)
- `is_active` - Cliente ativo
### AffiliateCommission
- `affiliate_id` - Afiliado
- `referral_id` - Indicação
- `payment_id` - Pagamento que gerou a comissão
- `type` - initial_sale, renewal, level_2
- `renewal_number` - Número da renovação (0 = venda inicial)
- `commission_rate` - Taxa (20.00, 15.00, 10.00, 5.00)
- `commission_amount` - Valor da comissão
- `status` - pending, approved, paid, cancelled
- `approved_at` - Data de aprovação
- `paid_at` - Data de pagamento
### AffiliatePayout
- `affiliate_id` - Afiliado
- `amount` - Valor total
- `commission_count` - Quantidade de comissões
- `pix_key`, `pix_key_type`, `pix_name` - Dados PIX usados
- `status` - pending, processing, paid, failed, cancelled
- `transaction_id` - ID da transação PIX
## ⚠️ Observações Importantes
1. **Auto-referência**: Sistema impede que afiliado se auto-referencie
2. **Aprovação obrigatória**: Novos afiliados precisam ser aprovados pelo admin
3. **30 dias de espera**: Comissões só podem ser pagas após 30 dias da aprovação
4. **Validação de limites**: Sistema valida se downgrade é possível (não implementado ainda para afiliados)
5. **Nível 2**: Preparado mas não implementado (requer sistema de sub-afiliados)
## 🚀 Como Testar
1. Executar migrations
2. Adicionar rotas
3. Adicionar middleware
4. Atualizar RegisterPage e AuthContext
5. Adicionar links no sidebar
6. Testar fluxo completo:
- Criar conta de afiliado
- Aprovar como admin
- Compartilhar link
- Registrar novo usuário com link
- Fazer pagamento
- Verificar comissão criada
- Aguardar 30 dias ou aprovar manualmente
- Criar payout
- Marcar como pago