# Sistema Financeiro - Saldos, Comissões e Saques

## 📋 Visão Geral

O sistema financeiro gerencia saldos, comissões e saques para produtores e afiliados. Mantém o fluxo de pagamento na conta do admin, mas calcula e registra comissões automaticamente quando vendas são aprovadas.

---

## 🗄️ Estrutura das Tabelas

### Tabela `saldos_usuarios`

Armazena os saldos de cada usuário.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | INT(11) | Chave primária, auto-incremento |
| `usuario_id` | INT(11) | ID do usuário (UNIQUE) |
| `saldo_disponivel` | DECIMAL(10,2) | Saldo disponível para saque |
| `saldo_pendente` | DECIMAL(10,2) | Saldo pendente (período de garantia) |
| `saldo_bloqueado` | DECIMAL(10,2) | Saldo bloqueado (aguardando processamento de saque) |
| `updated_at` | DATETIME | Data de atualização |

**Índices:**
- PRIMARY KEY: `id`
- UNIQUE: `usuario_id`

### Tabela `saques`

Armazena solicitações de saque.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | INT(11) | Chave primária, auto-incremento |
| `usuario_id` | INT(11) | ID do usuário |
| `valor` | DECIMAL(10,2) | Valor solicitado |
| `status` | VARCHAR(20) | Status: pendente, aprovado, reprovado, pago |
| `forma_pagamento` | VARCHAR(50) | Forma: PIX, TED, DOC |
| `chave_pagamento` | VARCHAR(255) | Chave PIX ou dados bancários |
| `observacao` | TEXT | Observações do admin |
| `created_at` | DATETIME | Data de criação |
| `updated_at` | DATETIME | Data de atualização |

**Índices:**
- PRIMARY KEY: `id`
- KEY: `idx_usuario_id`, `idx_status`, `idx_created_at`

### Tabela `vendas_comissoes`

Registra comissões calculadas por venda.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | INT(11) | Chave primária, auto-incremento |
| `transacao_id` | INT(11) | ID da transação (UNIQUE) |
| `produtor_id` | INT(11) | ID do produtor |
| `afiliado_id` | INT(11) | ID do afiliado (NULL se não houver) |
| `valor_produtor` | DECIMAL(10,2) | Valor da comissão do produtor |
| `valor_afiliado` | DECIMAL(10,2) | Valor da comissão do afiliado |
| `valor_plataforma` | DECIMAL(10,2) | Valor da plataforma (futuro) |
| `created_at` | DATETIME | Data de criação |

**Índices:**
- PRIMARY KEY: `id`
- UNIQUE: `transacao_id`
- KEY: `idx_produtor_id`, `idx_afiliado_id`, `idx_created_at`

---

## 🔄 Migrações SQL

### 1. Saldos e Saques

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

Cria as tabelas `saldos_usuarios` e `saques`.

### 2. Vendas Comissões

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

Cria a tabela `vendas_comissoes`.

### Como Executar

1. Execute as migrações na ordem:
   ```sql
   -- 1. Criar tabelas de saldos e saques
   -- Execute: config/sql_migrations/2025_07_saldos_saques.sql
   
   -- 2. Criar tabela de comissões
   -- Execute: config/sql_migrations/2025_08_vendas_comissoes.sql
   ```

2. Verifique a migração:
   ```sql
   SELECT COUNT(*) FROM saldos_usuarios;
   SELECT COUNT(*) FROM saques;
   SELECT COUNT(*) FROM vendas_comissoes;
   ```

---

## 💰 Cálculo de Comissões

### Regra de Cálculo

Quando uma venda é aprovada:

1. **Busca comissão do afiliado** (se houver):
   - Percentual definido em `afiliacoes.comissao_valor`
   - Tipo: `percentual` (por enquanto)

2. **Calcula valores**:
   ```
   valor_afiliado = valor_total * (comissao_percentual / 100)
   valor_produtor = valor_total - valor_afiliado
   valor_plataforma = 0 (futuro)
   ```

3. **Registra em `vendas_comissoes`**:
   - Um registro por transação aprovada
   - Valores calculados e salvos

4. **Atualiza saldos**:
   - **Produtor**: Adiciona `valor_produtor` em `saldo_pendente`
   - **Afiliado**: Adiciona `valor_afiliado` em `saldo_pendente` (se houver)

### Onde é Calculado

- **Cartão de Crédito**: `backend/process_payment.php` (quando status = 'approved')
- **PIX**: `backend/webhook.php` (quando pagamento é aprovado via webhook)

### Função Helper

**Arquivo**: `backend/financeiro_helper.php`

Função principal: `calcular_e_registrar_comissoes()`

```php
calcular_e_registrar_comissoes(
    $transacao_id,
    $produto_id,
    $produtor_id,
    $afiliado_id, // null se não houver
    $valor_total
);
```

---

## 📊 Atualização de Saldos

### Tipos de Saldo

1. **Saldo Disponível** (`saldo_disponivel`):
   - Disponível para saque imediato
   - Movido de pendente após período de garantia

2. **Saldo Pendente** (`saldo_pendente`):
   - Comissões recém-calculadas
   - Aguardando período de garantia
   - Por padrão, todas as comissões entram como pendente

3. **Saldo Bloqueado** (`saldo_bloqueado`):
   - Saldo em processamento de saque
   - Bloqueado até aprovação/reprovação do saque

### Atualização Automática

Quando uma venda é aprovada:

1. Comissão é calculada
2. Saldo é adicionado em `saldo_pendente`:
   - Produtor recebe `valor_produtor`
   - Afiliado recebe `valor_afiliado` (se houver)

### Liberação de Saldo Pendente

**Função preparada** (não executada automaticamente ainda):

```php
// Em financeiro_helper.php
function liberar_saldos_pendentes($dias_garantia = 7)
```

Esta função pode ser chamada via:
- Cron job (recomendado)
- Interface admin (futuro)
- Script manual

**Lógica:**
- Busca comissões com mais de X dias
- Move de `saldo_pendente` para `saldo_disponivel`

---

## 💸 Sistema de Saques

### Solicitar Saque

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

**Processo:**

1. Usuário preenche formulário:
   - Valor do saque (máximo = saldo_disponivel)
   - Forma de pagamento (PIX, TED, DOC)
   - Chave PIX / Dados bancários

2. Sistema valida:
   - Valor > 0
   - Valor <= saldo_disponivel
   - Chave preenchida

3. Sistema cria registro:
   - `saques.status = 'pendente'`
   - Subtrai `valor` de `saldo_disponivel`
   - Adiciona `valor` em `saldo_bloqueado`

### Gestão de Saques (Admin)

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

**Ações disponíveis:**

1. **Aprovar**:
   - Status: `pendente` → `aprovado`
   - Saldo permanece bloqueado (aguardando pagamento)

2. **Reprovar**:
   - Status: `pendente` → `reprovado`
   - Saldo: `bloqueado` → `disponivel` (devolvido)

3. **Marcar como Pago**:
   - Status: `aprovado` → `pago`
   - Saldo: Subtrai de `bloqueado` (já foi pago)

4. **Adicionar Observação**:
   - Campo de observação editável
   - Útil para comunicação com usuário

---

## 👥 Área do Usuário - Financeiro

### Página Principal

**URL**: `dashboard/pages_usuario/financeiro.php`

**Exibe:**

1. **Cards de Saldo**:
   - Saldo Disponível
   - Saldo Pendente
   - Saldo Bloqueado

2. **Estatísticas**:
   - Total como Produtor (vendas + valor)
   - Total como Afiliado (vendas + valor)

3. **Últimas Vendas**:
   - Lista das 10 últimas vendas
   - Mostra tipo (produtor ou afiliado)
   - Valor da comissão

4. **Ações Rápidas**:
   - Botão "Solicitar Saque"
   - Botão "Meus Saques"

### Solicitar Saque

**URL**: `dashboard/pages_usuario/solicitar_saque.php`

- Formulário para solicitar saque
- Validação de saldo disponível
- Campos: valor, forma de pagamento, chave PIX

### Meus Saques

**URL**: `dashboard/pages_usuario/meus_saques.php`

- Histórico completo de saques
- Status de cada saque
- Observações do admin

---

## 🔧 Implementação Técnica

### Helper de Financeiro

**Arquivo**: `backend/financeiro_helper.php`

**Funções principais:**

1. `calcular_e_registrar_comissoes()`:
   - Calcula comissões
   - Registra em `vendas_comissoes`
   - Atualiza saldos

2. `atualizar_saldo_usuario()`:
   - Adiciona/subtrai saldo
   - Cria registro se não existir

3. `obter_saldo_usuario()`:
   - Retorna saldos do usuário

4. `liberar_saldos_pendentes()`:
   - Move saldo pendente para disponível
   - Preparada para uso futuro

### Integração com Pagamentos

**Cartão de Crédito** (`backend/process_payment.php`):

```php
if ($payment->status == 'approved') {
    // Atualizar transação
    // Calcular comissões
    calcular_e_registrar_comissoes(...);
}
```

**PIX** (`backend/webhook.php`):

```php
if ($payment->status == 'approved') {
    // Atualizar transação
    // Verificar se comissão já foi calculada
    // Calcular comissões se necessário
    calcular_e_registrar_comissoes(...);
}
```

---

## 📈 Relatórios e Estatísticas

### Área do Usuário

**Financeiro** (`dashboard/pages_usuario/financeiro.php`):

- Saldo disponível, pendente, bloqueado
- Total ganho como produtor
- Total ganho como afiliado
- Últimas 10 vendas

**Meus Saques** (`dashboard/pages_usuario/meus_saques.php`):

- Histórico completo de saques
- Status de cada saque
- Valores e datas

### Dashboard Admin

**Gestão de Saques** (`dashboard/pages/saques.php`):

- Lista todos os saques
- Filtro por status
- Ações: aprovar, reprovar, marcar como pago
- Campo de observação

**Pedidos** (`dashboard/pages/pedidos.php`):

- Exibe produtor e afiliado (já implementado)

---

## 🔄 Fluxo Completo

### 1. Venda Aprovada

```
Cliente compra → Pagamento aprovado → 
Calcular comissões → Registrar em vendas_comissoes → 
Atualizar saldos (pendente)
```

### 2. Solicitar Saque

```
Usuário solicita saque → 
Criar registro em saques (pendente) → 
Subtrair de disponível → Adicionar em bloqueado
```

### 3. Admin Aprova Saque

```
Admin aprova → Status: aprovado → 
Saldo permanece bloqueado (aguardando pagamento)
```

### 4. Admin Marca como Pago

```
Admin marca como pago → Status: pago → 
Subtrair de bloqueado (já foi pago)
```

### 5. Admin Reprova Saque

```
Admin reprova → Status: reprovado → 
Subtrair de bloqueado → Adicionar em disponível
```

---

## 📊 Consultas Úteis

### Verificar Saldos

```sql
-- Saldos de todos os usuários
SELECT u.nome, u.email, 
       su.saldo_disponivel, su.saldo_pendente, su.saldo_bloqueado
FROM usuarios u
LEFT JOIN saldos_usuarios su ON su.usuario_id = u.id
ORDER BY su.saldo_disponivel DESC;
```

### Comissões por Usuário

```sql
-- Total ganho como produtor
SELECT u.nome, 
       COUNT(vc.id) as total_vendas,
       SUM(vc.valor_produtor) as total_ganho
FROM usuarios u
INNER JOIN vendas_comissoes vc ON vc.produtor_id = u.id
INNER JOIN transacoes t ON t.id = vc.transacao_id
WHERE t.status = 'Aprovado'
GROUP BY u.id, u.nome
ORDER BY total_ganho DESC;

-- Total ganho como afiliado
SELECT u.nome,
       COUNT(vc.id) as total_vendas,
       SUM(vc.valor_afiliado) as total_ganho
FROM usuarios u
INNER JOIN vendas_comissoes vc ON vc.afiliado_id = u.id
INNER JOIN transacoes t ON t.id = vc.transacao_id
WHERE t.status = 'Aprovado'
GROUP BY u.id, u.nome
ORDER BY total_ganho DESC;
```

### Saques Pendentes

```sql
-- Saques aguardando aprovação
SELECT s.id, u.nome, s.valor, s.forma_pagamento, s.chave_pagamento, s.created_at
FROM saques s
INNER JOIN usuarios u ON u.id = s.usuario_id
WHERE s.status = 'pendente'
ORDER BY s.created_at ASC;
```

---

## 🚀 Próximos Passos

1. **Executar migrações SQL**: Execute as 2 migrações na ordem
2. **Testar cálculo de comissões**: Faça uma venda e verifique se as comissões são calculadas
3. **Testar saques**: Solicite um saque e teste aprovação/reprovação
4. **Configurar liberação automática**: Configure cron job para liberar saldos pendentes (opcional)

---

## ⚠️ Notas Importantes

- ⚠️ **Período de Garantia**: Por padrão, todas as comissões entram como pendente
- ⚠️ **Liberação Automática**: Função preparada, mas não executada automaticamente ainda
- ⚠️ **Validação**: Sistema valida saldo antes de permitir saque
- ⚠️ **Retrocompatibilidade**: Funciona mesmo sem as novas tabelas
- ⚠️ **Segurança**: Apenas usuários podem ver seus próprios saldos

---

## 🆘 Suporte

Em caso de dúvidas ou problemas:

1. Verifique se as migrações SQL foram executadas
2. Confirme que as tabelas existem
3. Verifique se as comissões estão sendo calculadas nas vendas
4. Confirme que os saldos estão sendo atualizados
5. Verifique os logs de erro do PHP

---

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


