# RELATÓRIO TÉCNICO: ANÁLISE E PLANEJAMENTO - INTEGRAÇÃO PAGAR.ME

**Data:** 2025-01-XX  
**Autor:** Sistema de Análise Técnica  
**Objetivo:** Mapear estrutura atual e planejar integração do gateway Pagar.me

---

## 1. MAPEAMENTO DA ESTRUTURA ATUAL DE GATEWAYS

### 1.1. Sistema de Seleção de Gateway

**Como funciona:**
- O sistema utiliza a função `gateway_ativado($gateway)` localizada em `backend/gateway_helper.php` (linha 40-43)
- Esta função consulta a tabela `configuracoes` buscando pela chave `{gateway}_enabled`
- Retorna `true` se o valor for `'1'` ou `1`, caso contrário `false`

**Variáveis PHP no checkout.php (linhas 46-54):**
```php
$mercadopago_ativado = gateway_ativado('mercadopago');
$stripe_ativado = gateway_ativado('stripe');
$paypal_ativado = gateway_ativado('paypal');
```

**Renderização Condicional:**
- As abas de pagamento são renderizadas condicionalmente baseadas nestas variáveis (linhas 1023-1042)
- A primeira aba ativa é determinada pela ordem: Mercado Pago > Stripe > PayPal
- Cada gateway tem sua própria div com ID específico: `#credit-card`, `#pix`, `#stripe`, `#paypal`

---

### 1.2. Armazenamento de Credenciais

**Tabela `configuracoes`:**
- Estrutura: `id`, `chave`, `valor`, `created_at`, `updated_at`
- Padrão de chaves: `{gateway}_{tipo_credencial}`
- Exemplos existentes:
  - Stripe: `stripe_public_key`, `stripe_secret_key`, `stripe_enabled`
  - PayPal: `paypal_client_id`, `paypal_client_secret`, `paypal_mode`, `paypal_enabled`
  - Mercado Pago: `mercadopago_access_token`, `mercadopago_public_key`, `mercadopago_enabled`

**Funções Helper:**
- `get_gateway_config($gateway, $key)` - Busca configuração específica
- `save_gateway_config($gateway, $key, $value)` - Salva configuração
- `get_all_gateway_config($gateway)` - Busca todas as configs de um gateway
- Localizadas em: `backend/gateway_helper.php`

**Nota:** Mercado Pago também utiliza `config/token.php` para compatibilidade, mas o sistema moderno usa a tabela `configuracoes`.

---

### 1.3. Arquivos de Processamento de Pagamento

Cada gateway possui seu próprio arquivo backend seguindo o padrão:

| Gateway | Arquivo | SDK/API | Métodos Suportados |
|---------|---------|---------|-------------------|
| Mercado Pago | `backend/process_payment.php` | SDK v3.5+ | Cartão de Crédito |
| Mercado Pago | `backend/process_payment_pix.php` | SDK v3.5+ | PIX |
| Stripe | `backend/process_payment_stripe.php` | Stripe PHP SDK | Cartão de Crédito |
| PayPal | `backend/process_payment_paypal.php` | cURL (REST API) | PayPal Checkout |

**Padrão Comum:**
1. Recebe JSON via `file_get_contents('php://input')`
2. Valida dados obrigatórios
3. Busca `produto_id` e `produtor_id` do banco
4. Insere transação na tabela `transacoes` com status 'Pendente'
5. Processa pagamento via API do gateway
6. Atualiza transação com `payment_id` e status final
7. Calcula e registra comissões (via `financeiro_helper.php`)
8. Retorna JSON com status

**Estrutura da Tabela `transacoes`:**
- Campos relevantes: `gateway`, `payment_id`, `status`, `tipo_pagamento`
- Todos os gateways usam a mesma tabela, diferenciados pelo campo `gateway`

---

## 2. PLANEJAMENTO DA INTEGRAÇÃO PAGAR.ME

### 2.1. Credenciais Necessárias (Pagar.me)

**Chaves Obrigatórias:**
- `api_key` - Chave de API (produção ou sandbox)
- `encryption_key` - Chave de criptografia para segurança de dados sensíveis

**Configurações Adicionais:**
- `enabled` - Ativar/desativar gateway (0 ou 1)
- `mode` - Ambiente (sandbox ou production) - opcional, pode ser inferido pela API key

**Armazenamento:**
- Seguir padrão existente: `pagarme_api_key`, `pagarme_encryption_key`, `pagarme_enabled`
- Salvar na tabela `configuracoes` via função `save_gateway_config('pagarme', 'api_key', $value)`

---

### 2.2. Arquivos a Criar

**1. `backend/process_payment_pagarme.php`**
- Processamento de pagamento via Pagar.me
- Seguir estrutura dos outros gateways
- Usar SDK oficial do Pagar.me ou cURL direto (verificar disponibilidade)

**2. Atualizações em `backend/gateway_helper.php`:**
- Adicionar Pagar.me na função `list_gateways_status()` (linha 118-139)
- Incluir informações: nome, suporta_cartao, suporta_pix

**3. Atualizações em `views/checkout.php`:**
- Variável: `$pagarme_ativado = gateway_ativado('pagarme');`
- Renderização da aba (similar às linhas 1032-1042)
- Renderização do conteúdo da aba (similar às linhas 1186-1265 para Stripe)

**4. Atualizações em `views/js/checkout.js`:**
- Função modular: `iniciarPagamentoPagarMe()`
- Event listener para botão de pagamento Pagar.me
- Integração com SDK JavaScript do Pagar.me (se disponível)

**5. Atualização em `dashboard/pages/credenciais.php`:**
- Formulário para configurar credenciais do Pagar.me
- Campos: API Key, Encryption Key, Checkbox "Ativar Pagar.me"

---

### 2.3. Métodos de Pagamento Suportados (Pagar.me)

**Cartão de Crédito:**
- Suportado ✅
- Requer SDK JavaScript no frontend (similar ao Mercado Pago)
- Processamento via backend com API Key

**PIX:**
- Suportado ✅
- Gera QR Code similar ao Mercado Pago
- Requer endpoint específico ou flag no mesmo arquivo

**Recomendação:** Criar dois arquivos separados:
- `backend/process_payment_pagarme.php` - Cartão
- `backend/process_payment_pagarme_pix.php` - PIX (ou unificar com flag)

---

## 3. CORREÇÃO DO BUG DE USABILIDADE (Page Reload)

### 3.1. Problema Identificado

**Situação Atual:**
- Botões de pagamento causam reload da página ao invés de processar via AJAX
- Event listeners não estão sendo anexados corretamente
- Múltiplos `DOMContentLoaded` podem causar conflitos

**Arquivos Afetados:**
- `views/js/checkout.js` - Lógica de eventos
- `views/checkout.php` - Estrutura HTML dos formulários

---

### 3.2. Solução Proposta (Arquitetura Modular)

**Estrutura JS Modular:**
```javascript
// Módulo de Gateway (Padrão a seguir)
const GatewayModule = {
    // Inicialização
    init: function() { ... },
    
    // Processamento
    processar: function(dados) { ... },
    
    // Validação
    validar: function() { ... }
};

// Implementações específicas
const MercadoPagoGateway = { ... };
const StripeGateway = { ... };
const PayPalGateway = { ... };
const PagarMeGateway = { ... }; // NOVO
```

**Padrão de Botões:**
- Todos os botões devem ter `type="button"` (não `submit`)
- Formulários devem ter `onsubmit="return false;"` ou `event.preventDefault()`
- Event listeners usando Event Delegation como fallback
- Feedback visual imediato (loading state)

**Estrutura de Função:**
```javascript
function iniciarPagamentoPagarMe() {
    // 1. Validação de dados
    // 2. Feedback visual (loading)
    // 3. Coleta de dados do formulário
    // 4. Fetch para backend
    // 5. Tratamento de resposta
    // 6. Redirecionamento ou exibição de erro
}
```

---

## 4. PLANO DE RECONSTRUÇÃO DO CHECKOUT

### Fase 1: Estrutura Base (Sem Alterar Funcionalidades Existentes)

1. **Refatorar `views/js/checkout.js`:**
   - Extrair lógica comum em funções utilitárias
   - Criar módulos por gateway (MercadoPago, Stripe, PayPal)
   - Implementar Event Delegation robusto
   - Adicionar logs detalhados para debug

2. **Blindagem de Formulários:**
   - Todos os forms devem prevenir submit nativo
   - Botões devem usar `type="button"`
   - Event listeners devem usar `preventDefault()` e `stopPropagation()`

---

### Fase 2: Integração Pagar.me

1. **Backend:**
   - Criar `backend/process_payment_pagarme.php`
   - Atualizar `backend/gateway_helper.php` (função `list_gateways_status()`)
   - Testar integração com API Pagar.me

2. **Frontend:**
   - Adicionar variável `$pagarme_ativado` em `checkout.php`
   - Renderizar aba Pagar.me condicionalmente
   - Criar função `iniciarPagamentoPagarMe()` em `checkout.js`
   - Integrar SDK JavaScript do Pagar.me (se necessário)

3. **Dashboard:**
   - Adicionar formulário de credenciais em `dashboard/pages/credenciais.php`
   - Implementar salvamento via `save_gateway_config()`

---

### Fase 3: Testes e Validação

1. **Testes Unitários:**
   - Verificar cada gateway isoladamente
   - Validar fluxo completo de cada método de pagamento

2. **Testes de Integração:**
   - Testar alternância entre gateways
   - Validar persistência de dados (produto_id, afiliado_id)
   - Verificar cálculos de comissões

3. **Testes de Usabilidade:**
   - Confirmar que não há page reload
   - Validar feedback visual em todas as etapas
   - Testar em diferentes navegadores

---

## 5. RESUMO EXECUTIVO

### Respostas às Perguntas:

**1. Como o sistema seleciona o gateway?**
- Via função `gateway_ativado($gateway)` que consulta `configuracoes.{gateway}_enabled`
- Variáveis PHP: `$mercadopago_ativado`, `$stripe_ativado`, `$paypal_ativado`
- Renderização condicional das abas no HTML

**2. Onde ficam as credenciais?**
- Tabela `configuracoes` com padrão `{gateway}_{tipo}`
- Funções helper: `get_gateway_config()`, `save_gateway_config()`
- Dashboard: `dashboard/pages/credenciais.php`

**3. Para adicionar Pagar.me, precisaremos:**
- Criar `backend/process_payment_pagarme.php`
- Adicionar campos na tabela `configuracoes`: `pagarme_api_key`, `pagarme_encryption_key`, `pagarme_enabled`
- Atualizar `gateway_helper.php` (função `list_gateways_status()`)
- Adicionar aba e lógica em `checkout.php` e `checkout.js`
- Criar formulário de credenciais no dashboard

**4. Plano de reconstrução:**
- Fase 1: Refatorar JS para estrutura modular e prevenir page reload
- Fase 2: Integrar Pagar.me seguindo padrão existente
- Fase 3: Testes completos de todos os gateways

---

## 6. RECOMENDAÇÕES TÉCNICAS

1. **Manter Compatibilidade:** Não remover código existente, apenas refatorar
2. **Padrão Consistente:** Seguir estrutura dos outros gateways
3. **Modularidade:** Separar lógica por gateway em módulos JS
4. **Error Handling:** Implementar tratamento robusto de erros
5. **Logging:** Adicionar logs detalhados para facilitar debug
6. **Documentação:** Documentar mudanças e novos padrões

---

**FIM DO RELATÓRIO**





