# 🎯 Funcionalidades Administrativas - Sistema de Afiliados

## 📋 Resumo das Novas Funcionalidades

Agora você tem controle total sobre o sistema de afiliados no painel administrativo!

### ✅ O Que Foi Implementado

1. **Gerenciamento de Afiliados**
   - ✅ Aprovar afiliados
   - ✅ Desqualificar afiliados
   - ✅ Bloquear afiliados (impede novas comissões)
   - ✅ Desbloquear afiliados
   - ✅ Ver detalhes completos (comissões, pagamentos, estatísticas)

2. **Gerenciamento de Comissões**
   - ✅ Listar todas as comissões de um afiliado
   - ✅ Invalidar comissões (pendentes ou aprovadas)
   - ✅ Ver histórico completo

3. **Gerenciamento de Pagamentos**
   - ✅ Listar todos os payouts de um afiliado
   - ✅ Marcar pagamento como realizado (com ID da transação PIX)
   - ✅ Cancelar pagamentos pendentes
   - ✅ Ver histórico completo

4. **Controle Avançado**
   - ✅ Ao bloquear, escolher se cancela ganhos não pagos
   - ✅ Motivos registrados para todas as ações
   - ✅ Logs detalhados de todas as operações

---

## 🎯 Como Usar

### **Acessar o Painel**

1. Login como administrador
2. Menu lateral → "Gerenciar Afiliados"

### **1️⃣ Aprovar ou Desqualificar Afiliados**

**Aprovar:**
- Clique no botão verde ✓ (Check)
- Confirme a aprovação
- O afiliado poderá gerar comissões

**Desqualificar:**
- Clique no botão vermelho ✗ (X)
- Informe o motivo da desqualificação
- Confirme a ação
- ⚠️ Comissões pendentes serão canceladas automaticamente

### **2️⃣ Bloquear Afiliado**

- Clique no botão laranja 🔒 (Lock)
- Informe o motivo do bloqueio
- **Escolha uma opção:**
  - ☐ Preservar ganhos não pagos
  - ☑ Cancelar ganhos não pagos (pendentes e aprovados)
- Confirme a ação

**O que acontece ao bloquear:**
- Novas comissões NÃO serão geradas
- Indicações existentes continuam vinculadas
- Se escolheu cancelar:
  - Comissões pendentes → canceladas
  - Comissões aprovadas → canceladas
  - Payouts pendentes → cancelados

**Desbloquear:**
- Clique no botão verde 🔓 (Unlock)
- Afiliado volta a gerar comissões normalmente

### **3️⃣ Ver Detalhes do Afiliado**

- Clique no botão azul 👁️ (Eye)
- **Modal com:**
  - Estatísticas (total ganho, pago, pendente)
  - Lista de comissões
  - Lista de pagamentos
  - Ações rápidas

### **4️⃣ Gerenciar Comissões**

**No modal de detalhes:**

**Invalidar Comissão:**
- Clique no botão vermelho 🚫 (Ban) na comissão
- Informe o motivo da invalidação
- Confirme a ação
- **Efeitos:**
  - Comissão marcada como "Cancelada"
  - Se estava vinculada a payout, é desvinculada
  - Estatísticas do afiliado são atualizadas
  - ⚠️ Não pode invalidar comissão já paga

### **5️⃣ Gerenciar Pagamentos**

**No modal de detalhes:**

**Marcar como Pago:**
- Clique no botão verde ✓ (Check) no payout
- Digite o ID da transação PIX (opcional)
- Confirme o pagamento
- **Efeitos:**
  - Payout marcado como "Pago"
  - Todas as comissões vinculadas marcadas como "Pago"
  - Estatísticas atualizadas

**Cancelar Pagamento:**
- Clique no botão vermelho ⭕ (XCircle) no payout
- Informe o motivo do cancelamento
- Confirme a ação
- **Efeitos:**
  - Payout marcado como "Cancelado"
  - Comissões voltam a ficar disponíveis para novo payout
  - Estatísticas atualizadas
  - ⚠️ Não pode cancelar pagamento já realizado

---

## 📊 Filtros Disponíveis

- **Todos:** Exibe todos os afiliados
- **Pendentes:** Apenas aguardando aprovação
- **Aprovados:** Aprovados mas podem estar inativos
- **Ativos:** Aprovados e ativos (gerando comissões)
- **Bloqueados:** Bloqueados pelo administrador

---

## 🔐 Segurança e Logs

Todas as ações são registradas em logs detalhados:

```php
- Quem executou a ação
- Quando foi executada
- Motivo informado
- Dados antes e depois
- Comissões/payouts afetados
```

**Localização dos logs:**
```bash
/var/www/gestorstream/backend/storage/logs/laravel.log
```

**Ver logs de afiliados:**
```bash
tail -f /var/www/gestorstream/backend/storage/logs/laravel.log | grep -i affiliate
```

---

## 🚀 Migração do Banco de Dados

### **Executar no Servidor:**

```bash
cd /var/www/gestorstream/backend
php artisan migrate
```

**Migrations adicionadas:**
1. `add_block_fields_to_affiliates_table` - Campos de bloqueio
2. `add_cancellation_fields_to_affiliate_commissions_table` - Campos de cancelamento
3. `add_cancellation_fields_to_affiliate_payouts_table` - Campos de cancelamento

---

## 📝 Novas Rotas da API

### **Administrador:**

```
GET    /api/v1/admin/affiliates                          - Listar afiliados
GET    /api/v1/admin/affiliates/{id}                     - Detalhes do afiliado
GET    /api/v1/admin/affiliates/{id}/commissions         - Comissões do afiliado
GET    /api/v1/admin/affiliates/{id}/payouts             - Pagamentos do afiliado

POST   /api/v1/admin/affiliates/{id}/approve             - Aprovar afiliado
POST   /api/v1/admin/affiliates/{id}/reject              - Desqualificar afiliado
POST   /api/v1/admin/affiliates/{id}/block               - Bloquear afiliado
POST   /api/v1/admin/affiliates/{id}/unblock             - Desbloquear afiliado

POST   /api/v1/admin/affiliates/commissions/{id}/invalidate  - Invalidar comissão

GET    /api/v1/admin/affiliates/payouts                  - Listar todos os payouts
POST   /api/v1/admin/affiliates/payouts/{id}/paid        - Marcar como pago
POST   /api/v1/admin/affiliates/payouts/{id}/cancel      - Cancelar pagamento
```

---

## 📋 Estrutura dos Dados

### **Affiliate (Afiliado)**
```json
{
  "id": 1,
  "user_id": 10,
  "code": "ABC12345",
  "approved": true,
  "active": true,
  "block_reason": null,
  "blocked_at": null,
  "blocked_by": null,
  "total_earnings": "150.00",
  "paid_earnings": "50.00",
  "pending_earnings": "100.00"
}
```

### **AffiliateCommission (Comissão)**
```json
{
  "id": 1,
  "affiliate_id": 1,
  "type": "initial_sale",
  "commission_amount": "20.00",
  "status": "approved",
  "cancelled_at": null,
  "cancellation_reason": null
}
```

### **AffiliatePayout (Pagamento)**
```json
{
  "id": 1,
  "affiliate_id": 1,
  "amount": "100.00",
  "commission_count": 5,
  "status": "paid",
  "paid_at": "2026-01-12T10:00:00",
  "transaction_id": "PIX123456",
  "cancelled_at": null,
  "cancellation_reason": null
}
```

---

## ⚠️ Regras de Negócio

### **Bloqueio de Afiliado**
- ✅ Pode bloquear afiliado aprovado e ativo
- ✅ Pode escolher cancelar ou preservar ganhos não pagos
- ❌ Não pode gerar novas comissões enquanto bloqueado
- ✅ Pode desbloquear a qualquer momento

### **Invalidação de Comissão**
- ✅ Pode invalidar comissões pendentes
- ✅ Pode invalidar comissões aprovadas
- ❌ NÃO pode invalidar comissões já pagas
- ✅ Se estava vinculada a payout, é desvinculada

### **Cancelamento de Pagamento**
- ✅ Pode cancelar payouts pendentes
- ✅ Pode cancelar payouts em processamento
- ❌ NÃO pode cancelar payouts já pagos
- ✅ Comissões voltam a ficar disponíveis

### **Desqualificação**
- ✅ Apenas afiliados não aprovados
- ⚠️ Cancela comissões pendentes automaticamente
- ❌ Não pode ser desfeita

---

## 🎯 Casos de Uso

### **Caso 1: Afiliado Fraudulento**
1. Bloquear afiliado
2. Marcar "Cancelar ganhos não pagos"
3. Motivo: "Atividade fraudulenta detectada"
4. ✅ Todas as comissões pendentes e aprovadas são canceladas
5. ✅ Novas comissões não são geradas

### **Caso 2: Comissão Indevida**
1. Ver detalhes do afiliado
2. Localizar a comissão problemática
3. Clicar em "Invalidar"
4. Motivo: "Pagamento estornado pelo cliente"
5. ✅ Comissão cancelada
6. ✅ Se estava em payout, é removida

### **Caso 3: Cancelar Pagamento por Erro**
1. Ver detalhes do afiliado
2. Localizar o payout
3. Clicar em "Cancelar Pagamento"
4. Motivo: "Dados PIX incorretos"
5. ✅ Payout cancelado
6. ✅ Comissões voltam a ficar disponíveis
7. ✅ Pode criar novo payout

### **Caso 4: Processar Pagamento**
1. Ver detalhes do afiliado
2. Localizar payout pendente
3. Realizar transferência PIX manualmente
4. Clicar em "Marcar como Pago"
5. Informar ID da transação PIX
6. ✅ Payout e comissões marcados como pagos
7. ✅ Estatísticas atualizadas

---

## 📊 Relatórios e Consultas SQL

### **Afiliados Bloqueados com Ganhos Cancelados**
```sql
SELECT 
    a.id,
    u.name,
    a.block_reason,
    a.blocked_at,
    COUNT(ac.id) as comissoes_canceladas,
    SUM(ac.commission_amount) as valor_cancelado
FROM affiliates a
JOIN users u ON a.user_id = u.id
LEFT JOIN affiliate_commissions ac ON a.id = ac.affiliate_id AND ac.status = 'cancelled'
WHERE a.active = false AND a.blocked_at IS NOT NULL
GROUP BY a.id;
```

### **Comissões Invalidadas**
```sql
SELECT 
    ac.id,
    u.name as afiliado,
    ac.commission_amount,
    ac.cancelled_at,
    ac.cancellation_reason
FROM affiliate_commissions ac
JOIN affiliates a ON ac.affiliate_id = a.id
JOIN users u ON a.user_id = u.id
WHERE ac.status = 'cancelled' AND ac.cancelled_at IS NOT NULL
ORDER BY ac.cancelled_at DESC;
```

---

## 🎉 Benefícios

1. ✅ **Controle Total** - Gerencie cada aspecto do sistema de afiliados
2. ✅ **Flexibilidade** - Bloqueie sem perder dados ou cancele tudo
3. ✅ **Auditoria** - Todos os motivos e ações registrados
4. ✅ **Segurança** - Múltiplas confirmações para ações críticas
5. ✅ **Transparência** - Logs detalhados de todas as operações
6. ✅ **Eficiência** - Ações rápidas direto no painel

---

## 🔄 Fluxo Completo de Gestão

```
1. Novo afiliado se cadastra
   ↓
2. Admin aprova ou rejeita
   ↓
3. Afiliado gera indicações
   ↓
4. Indicações pagam → comissões criadas
   ↓
5. Após 30 dias → comissões aprovadas
   ↓
6. Admin cria payout com comissões aprovadas
   ↓
7. Admin processa PIX e marca como pago
   ↓
8. Estatísticas atualizadas automaticamente
```

**Controles durante o processo:**
- ⚙️ Bloquear afiliado a qualquer momento
- ⚙️ Invalidar comissões específicas
- ⚙️ Cancelar payouts se necessário
- ⚙️ Desbloquear e reprocessar

---

## 📞 Suporte

Se tiver dúvidas ou problemas:

1. Verifique os logs:
   ```bash
   tail -100 /var/www/gestorstream/backend/storage/logs/laravel.log | grep -i affiliate
   ```

2. Teste as ações em modo teste primeiro

3. Todas as ações (exceto desqualificar) podem ser revertidas

---

## ✅ Checklist de Implementação

- [x] Migrations criadas
- [x] Models atualizados
- [x] Controller com todas as funções
- [x] Rotas adicionadas
- [x] Frontend completo
- [x] Modais para todas as ações
- [x] Confirmações de segurança
- [x] Logs detalhados
- [x] Documentação completa

**Status: 100% Implementado! 🎉**

Execute as migrations e está pronto para usar!

```bash
cd /var/www/gestorstream/backend
php artisan migrate
```