# Diagnóstico Técnico - Configurações Financeiras Dinâmicas
**Data:** 2025  
**Sistema:** Checkout Pro 2025  
**Objetivo:** Mapear estrutura para implementar configurações dinâmicas de taxas e limites

---

## 📋 RESUMO EXECUTIVO

O sistema possui **duas tabelas de configurações** disponíveis:
1. **`configuracoes`** (legado) - Estrutura simples (`chave`, `valor`)
2. **`system_settings`** (moderna) - Estrutura completa com tipos e cache

**Recomendação:** Utilizar `system_settings` para novas configurações financeiras, pois já possui suporte a tipos e cache de sessão.

---

## 1. 🗄️ BANCO DE DADOS - Estrutura Atual

### Tabelas de Configuração Disponíveis

#### A) Tabela `system_settings` (RECOMENDADA)
**Localização:** `config/sql_migrations/2025_11_white_label_system.sql`  
**Helper:** `backend/settings_helper.php`

**Estrutura:**
```sql
CREATE TABLE `system_settings` (
    `id` INT(11) NOT NULL AUTO_INCREMENT,
    `setting_key` VARCHAR(100) NOT NULL UNIQUE,
    `setting_value` TEXT DEFAULT NULL,
    `setting_type` VARCHAR(50) DEFAULT 'text',
    `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;
```

**Status:** ✅ Tabela existe e está funcional  
**Vantagens:**
- Funções helper prontas (`getSystemSetting()`, `setSystemSetting()`)
- Cache automático em `$_SESSION`
- Suporte a tipos (`text`, `number`, `color`, etc.)

#### B) Tabela `configuracoes` (LEGADO)
**Localização:** `checkout_pro_2025_completo.sql` (linha 175)

**Estrutura:**
```sql
CREATE TABLE `configuracoes` (
    `id` INT(11) NOT NULL AUTO_INCREMENT,
    `chave` VARCHAR(191) NOT NULL UNIQUE,
    `valor` TEXT DEFAULT NULL,
    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB;
```

**Status:** ✅ Tabela existe (usada para credenciais de gateways)  
**Desvantagem:** Não possui helper específico (queries manuais necessárias)

---

## 2. ⚙️ CONFIGURAÇÕES NECESSÁRIAS A CRIAR

### Configurações Financeiras (Novas Colunas/Registros)

As seguintes configurações **NÃO EXISTEM** e precisam ser criadas na tabela `system_settings`:

| Chave | Tipo Sugerido | Descrição | Valor Padrão Sugerido |
|-------|---------------|-----------|----------------------|
| `taxa_plataforma_venda_tipo` | `text` | Tipo de taxa: `percentual` ou `fixo` | `percentual` |
| `taxa_plataforma_venda_valor` | `number` | Valor da taxa (5 para 5% ou 1.00 para R$ 1,00) | `5` |
| `taxa_saque` | `number` | Taxa fixa por saque (ex: 3.00 = R$ 3,00) | `3.00` |
| `prazo_liberacao_dias` | `number` | Dias para liberar saldo pendente (ex: 30) | `30` |
| `saque_minimo` | `number` | Valor mínimo por saque (ex: 20.00 = R$ 20,00) | `20.00` |
| `saque_maximo` | `number` | Valor máximo por saque (ex: 10000.00 = R$ 10.000,00) | `10000.00` |

---

## 3. 📊 LÓGICA DE CÁLCULO - Estado Atual

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

#### Função: `calcular_e_registrar_comissoes()`
**Linha 53:** Taxa da plataforma está **HARDCODED**:

```php
$valor_plataforma = 0; // Por enquanto, plataforma não cobra taxa
```

**Problema:** 
- ❌ Taxa está fixa em `0`
- ❌ Não considera configuração dinâmica
- ✅ Coluna `valor_plataforma` já existe na tabela `vendas_comissoes`

**Cálculo Atual:**
```php
// Linha 50-58
$valor_afiliado = 0;
$valor_produtor = $valor_total;  // Produtor recebe 100%
$valor_plataforma = 0;            // Plataforma recebe 0%

if ($afiliado_id && $comissao_afiliado_percentual > 0) {
    $valor_afiliado = round($valor_total * ($comissao_afiliado_percentual / 100), 2);
    $valor_produtor = round($valor_total - $valor_afiliado, 2);  // Produtor recebe resto
}
```

**Onde é chamado:**
- `backend/process_payment.php` (linha 257) - Pagamento Mercado Pago
- `backend/process_payment_stripe.php` (linha 206) - Pagamento Stripe
- `backend/process_payment_paypal.php` - Pagamento PayPal
- `backend/webhook.php` (linha 74) - Webhook Mercado Pago

---

## 4. 📅 PRAZO DE LIBERAÇÃO - Estado Atual

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

#### Função: `liberar_saldos_pendentes()`
**Linha 159:** Função existe mas está **DESATIVADA**

```php
function liberar_saldos_pendentes($dias_garantia = 7) {
    // ...
    // Nota: Esta função é preparada para uso futuro via cron job ou interface admin
    // Por enquanto, está comentada para não executar automaticamente
    return 0;
}
```

**Problema:**
- ❌ Dias de garantia está fixo em `7` (hardcoded)
- ❌ Função não está sendo executada (retorna 0)
- ❌ Não considera configuração dinâmica do banco
- ⚠️ Query SQL existe (linha 168): `DATE_ADD(vc.created_at, INTERVAL :dias DAY)`

**Status Atual:**
- Todas as comissões são adicionadas em `saldo_pendente` (linha 83)
- Não há processo automático para mover de `pendente` para `disponivel`
- O admin precisa fazer manualmente ou via script externo

---

## 5. 💸 SISTEMA DE SAQUES - Estado Atual

### Arquivo: `dashboard/pages_usuario/solicitar_saque.php`

#### Validações Atuais (linhas 36-41):

```php
if ($valor <= 0) {
    $erro = 'O valor deve ser maior que zero.';
} elseif ($valor > $saldo_disponivel) {
    $erro = 'O valor solicitado é maior que o saldo disponível.';
} elseif (empty($chave_pagamento)) {
    $erro = 'A chave de pagamento é obrigatória.';
}
```

**Problemas Identificados:**

1. **❌ Valor Mínimo:**
   - Não existe validação de valor mínimo
   - Qualquer valor acima de 0 é aceito
   - Precisará adicionar: `if ($valor < getSystemSetting('saque_minimo', 20.00))`

2. **❌ Valor Máximo:**
   - Só valida contra `saldo_disponivel`
   - Não existe limite máximo configurável
   - Precisará adicionar: `if ($valor > getSystemSetting('saque_maximo', 10000.00))`

3. **❌ Taxa de Saque:**
   - Não existe cobrança de taxa no momento do saque
   - Linha 58: apenas subtrai do `saldo_disponivel` e adiciona em `bloqueado`
   - Não há registro de taxa paga
   - **Recomendação:** Subtrair taxa ANTES de bloquear ou criar campo `taxa_cobrada` na tabela `saques`

#### Tabela `saques` (estrutura):
- ✅ Campo `valor` existe (valor solicitado)
- ❌ Campo `taxa_cobrada` NÃO existe (será necessário adicionar para rastreamento)

---

## 6. 🎨 PÁGINA DE CONFIGURAÇÕES DO ADMIN

### Arquivo: `dashboard/pages/configuracoes_admin.php`

**Estado Atual:**
- ✅ Arquivo existe
- ❌ Focado apenas em perfil do admin (foto e senha)
- ❌ Não possui seção para configurações financeiras
- ✅ Estrutura de cards e formulários pronta para expansão

**Espaço Disponível:**
- Linha 172-257: Container principal com 2 cards
- **Recomendação:** Adicionar novo card "Configurações Financeiras" após o card "Alterar Senha"

---

## 7. 📝 RESUMO TÉCNICO - Alterações Necessárias

### ✅ ESTRUTURAS QUE JÁ EXISTEM:

1. **Tabela `system_settings`** - Pronta para uso
2. **Helper `settings_helper.php`** - Funções `getSystemSetting()` e `setSystemSetting()` disponíveis
3. **Coluna `valor_plataforma`** na tabela `vendas_comissoes` - Existe e está sendo salva (sempre 0)
4. **Função `liberar_saldos_pendentes()`** - Existe mas desativada
5. **Página `configuracoes_admin.php`** - Existe e pode ser expandida

### ❌ ALTERAÇÕES NECESSÁRIAS:

#### A) Banco de Dados:

**1. Inserir configurações iniciais na `system_settings`:**
```sql
INSERT INTO system_settings (setting_key, setting_value, setting_type) VALUES
('taxa_plataforma_venda_tipo', 'percentual', 'text'),
('taxa_plataforma_venda_valor', '5', 'number'),
('taxa_saque', '3.00', 'number'),
('prazo_liberacao_dias', '30', 'number'),
('saque_minimo', '20.00', 'number'),
('saque_maximo', '10000.00', 'number');
```

**2. Adicionar coluna na tabela `saques` (opcional, para rastreamento):**
```sql
ALTER TABLE saques ADD COLUMN taxa_cobrada DECIMAL(10,2) DEFAULT 0.00 
COMMENT 'Taxa cobrada no saque' AFTER valor;
```

#### B) Backend - Cálculo de Comissões:

**Arquivo:** `backend/financeiro_helper.php`  
**Função:** `calcular_e_registrar_comissoes()`  
**Linha 53:** Substituir:

```php
// ANTES (hardcoded)
$valor_plataforma = 0; // Por enquanto, plataforma não cobra taxa

// DEPOIS (dinâmico)
require_once __DIR__ . '/settings_helper.php';
$taxa_tipo = getSystemSetting('taxa_plataforma_venda_tipo', 'percentual');
$taxa_valor = floatval(getSystemSetting('taxa_plataforma_venda_valor', 0));

if ($taxa_tipo === 'percentual' && $taxa_valor > 0) {
    $valor_plataforma = round($valor_total * ($taxa_valor / 100), 2);
} elseif ($taxa_tipo === 'fixo' && $taxa_valor > 0) {
    $valor_plataforma = round($taxa_valor, 2);
} else {
    $valor_plataforma = 0;
}

// Ajustar valor do produtor após taxa da plataforma
$valor_produtor = round($valor_total - $valor_plataforma, 2);

// Se houver afiliado, calcular sobre o valor já descontado da plataforma
if ($afiliado_id && $comissao_afiliado_percentual > 0) {
    $valor_afiliado = round($valor_produtor * ($comissao_afiliado_percentual / 100), 2);
    $valor_produtor = round($valor_produtor - $valor_afiliado, 2);
}
```

#### C) Backend - Liberação de Saldos:

**Arquivo:** `backend/financeiro_helper.php`  
**Função:** `liberar_saldos_pendentes()`  
**Linha 159:** Substituir parâmetro fixo:

```php
// ANTES (hardcoded)
function liberar_saldos_pendentes($dias_garantia = 7) {

// DEPOIS (dinâmico)
require_once __DIR__ . '/settings_helper.php';
function liberar_saldos_pendentes($dias_garantia = null) {
    if ($dias_garantia === null) {
        $dias_garantia = intval(getSystemSetting('prazo_liberacao_dias', 30));
    }
    // ... resto da função permanece igual
```

#### D) Frontend - Solicitar Saque:

**Arquivo:** `dashboard/pages_usuario/solicitar_saque.php`  
**Linha 36:** Adicionar validações:

```php
// ANTES
if ($valor <= 0) {
    $erro = 'O valor deve ser maior que zero.';
}

// DEPOIS
require_once __DIR__ . '/../../backend/settings_helper.php';
$saque_minimo = floatval(getSystemSetting('saque_minimo', 20.00));
$saque_maximo = floatval(getSystemSetting('saque_maximo', 10000.00));

if ($valor <= 0) {
    $erro = 'O valor deve ser maior que zero.';
} elseif ($valor < $saque_minimo) {
    $erro = "O valor mínimo para saque é R$ " . number_format($saque_minimo, 2, ',', '.');
} elseif ($valor > $saque_maximo) {
    $erro = "O valor máximo para saque é R$ " . number_format($saque_maximo, 2, ',', '.');
}
```

**Linha 58:** Adicionar cobrança de taxa:

```php
// ANTES
atualizar_saldo_usuario($usuario_id, $valor, 'disponivel', 'subtrair');

// DEPOIS
$taxa_saque = floatval(getSystemSetting('taxa_saque', 3.00));
$valor_total_retirado = $valor + $taxa_saque;  // Valor + Taxa

if ($valor_total_retirado > $saldo_disponivel) {
    $erro = 'Saldo insuficiente para cobrir o valor do saque + taxa.';
    // ... retornar erro
}

atualizar_saldo_usuario($usuario_id, $valor_total_retirado, 'disponivel', 'subtrair');
```

**Linha 47:** Atualizar INSERT para incluir taxa:

```sql
-- ANTES
INSERT INTO saques (usuario_id, valor, status, forma_pagamento, chave_pagamento, created_at, updated_at)

-- DEPOIS (se adicionar coluna taxa_cobrada)
INSERT INTO saques (usuario_id, valor, taxa_cobrada, status, forma_pagamento, chave_pagamento, created_at, updated_at)
VALUES (:usuario_id, :valor, :taxa_cobrada, 'pendente', :forma_pagamento, :chave_pagamento, NOW(), NOW())
```

#### E) Frontend - Página de Configurações Admin:

**Arquivo:** `dashboard/pages/configuracoes_admin.php`  
**Ação:** Adicionar novo card após linha 256:

```php
<!-- Configurações Financeiras -->
<div class="card">
    <h3><i class="fas fa-money-bill-wave"></i> Configurações Financeiras</h3>
    <form method="POST">
        <input type="hidden" name="acao" value="salvar_config_financeiro">
        
        <!-- Taxa por Venda -->
        <div class="form-group">
            <label>Tipo de Taxa por Venda</label>
            <select name="taxa_venda_tipo">
                <option value="percentual">Percentual (%)</option>
                <option value="fixo">Valor Fixo (R$)</option>
            </select>
        </div>
        
        <div class="form-group">
            <label>Valor da Taxa por Venda</label>
            <input type="number" name="taxa_venda_valor" step="0.01">
        </div>
        
        <!-- Taxa de Saque -->
        <div class="form-group">
            <label>Taxa por Saque (R$)</label>
            <input type="number" name="taxa_saque" step="0.01">
        </div>
        
        <!-- Prazo de Liberação -->
        <div class="form-group">
            <label>Prazo de Liberação (dias)</label>
            <input type="number" name="prazo_liberacao" min="1">
        </div>
        
        <!-- Limites de Saque -->
        <div class="form-group">
            <label>Valor Mínimo de Saque (R$)</label>
            <input type="number" name="saque_minimo" step="0.01">
        </div>
        
        <div class="form-group">
            <label>Valor Máximo de Saque (R$)</label>
            <input type="number" name="saque_maximo" step="0.01">
        </div>
        
        <button type="submit">Salvar Configurações</button>
    </form>
</div>
```

---

## 8. 📊 FLUXO DE CÁLCULO PROPOSTO

### Venda sem Afiliado:
```
Valor Total: R$ 100,00
Taxa Plataforma (5%): R$ 5,00
Produtor recebe: R$ 95,00
```

### Venda com Afiliado (10%):
```
Valor Total: R$ 100,00
Taxa Plataforma (5%): R$ 5,00
Valor após Plataforma: R$ 95,00
Comissão Afiliado (10% de R$ 95,00): R$ 9,50
Produtor recebe: R$ 85,50
```

### Saque:
```
Valor Solicitado: R$ 100,00
Taxa de Saque: R$ 3,00
Total Retirado do Saldo: R$ 103,00
```

---

## 9. ✅ CONCLUSÃO

**Status Geral:** ✅ **VIÁVEL** - Todas as estruturas necessárias existem ou são facilmente implementáveis.

**Principais Pontos:**
1. ✅ Tabela `system_settings` existe e possui helper pronto
2. ❌ Taxa da plataforma está hardcoded em `0` (linha 53 de `financeiro_helper.php`)
3. ❌ Prazo de liberação está hardcoded em `7 dias` (linha 159)
4. ❌ Validações de saque não consideram mín/máx configuráveis
5. ❌ Taxa de saque não é cobrada no momento da solicitação
6. ✅ Página de configurações existe e pode ser expandida

**Complexidade de Implementação:** 🟡 **MÉDIA**
- Mudanças são pontuais e isoladas
- Não requer alteração de estrutura de banco complexa
- Helper de configurações já está pronto para uso

**Riscos:**
- ⚠️ Alterar cálculo de comissões pode afetar saldos existentes (necessário migração de dados se necessário)
- ⚠️ Taxa de saque retroativa não deve ser aplicada em saques já processados
- ⚠️ Testes extensivos necessários para garantir que cálculos estão corretos

---

**Relatório gerado por:** Sistema de Análise Técnica  
**Data:** 2025







