Alahubs Checkout

• Isolamento de microserviço: Serviço NestJS separado desacoplado da plataforma Alahubs principal permite escalonamento independente de pagamentos, upgrades de framework e domínios de falha isolados. Processa 5mil+ transações diárias entre 2 provedores sem impactar operações de usuários.
• Camada de abstração dual de processadores: Stripe (subscrições em USD) + Mercado Pago (pedidos em BRL) unificados através de único endpoint /payments/process/stripe/cc com modelo de transação agnóstico a provedor. Chaves de idempotência previnem dupla cobrança em retentativas; cron de reconciliação detecta discrepâncias entre provedores.
• Migração de Prisma ORM para PostgreSQL nativo: Migrado de Prisma para driver pg nativo (pool de 20 conexões) alcançando controle direto de queries e redução de 15% em latência. DatabaseService gerencia ciclo de vida de conexões; queries parametrizadas previnem SQL injection; suporte a transações para operações atômicas.
• Quatro entidades principais e repositórios: Produtos, Compras, Cartões de Clientes, Cupons modelados como interfaces TypeScript apoiadas pelo padrão repository. ProductsRepository, CustomerCardRepository, CouponsRepository, PurchasesRepository encapsulam acesso ao BD com query builders type-safe.
• Integrações de eventos em tempo real: Alertas Discord webhook para falhas de pagamento, transações bem-sucedidas e atualizações de receita transmitidas para times de vendas. Rastreamento Meta Ads via PII com hash SHA256 (email, primeiro/último nome) enviado à API de Pixel de Anúncios para atribuição de leads entre campanhas.

alahubs-checkout-architecture

• Driver PostgreSQL nativo (pg) em vez de ORM Prisma: Camada de abstração mais baixa requer SQL manual, mas habilita otimização de queries, controle de pool de conexões e queries sem overhead. Eliminou problemas de schema drift do Prisma e adicionou melhoria de 15% em latência para processamento de pagamentos em alto volume.
• Padrão Repository para abstração de acesso a dados: Indireção extra (Repository → DatabaseService → pg driver) mas oferece testabilidade, mantibilidade e desacoplamento de implementação de BD. Fácil trocar PostgreSQL por outro banco ou adicionar camada de cache sem tocar em serviços.
• Endpoint de pagamento unificado mascarando diferenças do provedor: Único endpoint /payments/process/stripe/cc internamente roteia baseado no campo provider. Simplifica integração frontend, mas requer mapeamento cuidado de erros—Stripe e Mercado Pago retornam formatos de resposta e códigos de status diferentes.
• Chaves de idempotência para confiabilidade de pagamentos: Toda requisição inclui idempotencyKey (hash de usuário + produto + montante). APIs Stripe/Mercado Pago deduplicam retentativas. Adiciona complexidade aos DTOs e caching de resposta mas previne dupla cobrança em falhas de rede.
• Processamento de pagamento síncrono (sem fila de jobs ainda): Endpoint de pagamento bloqueia até Stripe/Mercado Pago responder (latência >500ms). Evita complexidade de Bull/RabbitMQ mas impactado por lentidão de API do provedor. Melhoria planejada: assíncrono com callbacks de webhook.

• Reconciliação de subscrição multi-moeda: Stripe cobra em USD com subscrições mensais; Mercado Pago processa BRL via API de pedidos sem modelo nativo de subscrição. Resolvido com enum BillingType (ONE_TIME, SUBSCRIPTION) e lógica específica por provedor em PaymentsService. Conversão de moeda cacheada; subscrições Mercado Pago emuladas via criação de pedido recorrente + verificações agendadas por cron.
• Queries parametrizadas type-safe sem ORM: PostgreSQL raw requer binding manual de parâmetros ($1, $2, etc.). Resolvido construindo utilitários de query builder e interfaces TypeScript estritas para formas de entidades. Repositórios escondem detalhes de queries; serviços trabalham com objetos de domínio apenas.
• Aplicação de cupom entre mix de produtos: Requisição única pode conter múltiplos produtos (pedidos e subscrições) com descontos variando. Resolvido com repositório de cupom rastreando quais produtos um cupom se aplica; cálculo de desconto soma reduções por-produto antes do processamento de pagamento. Previne ataques de combinação inválida de cupom.
• Hashing de PII para Meta Ads sem vazar dados: Deve enviar email/nome de usuário à API de Pixel Meta para rastreamento de lead, mas não pode armazenar PII em plaintext. Resolvido com hashing SHA256 no momento da requisição de pagamento; valores hashed enviados ao Pixel de Anúncios e armazenados em logs de auditoria. PII raw nunca persistido; pode ser re-hashorizado de requisição se necessário.
• Esgotamento de pool de conexão sob carga: Alto volume de transação pode esgotar pool de 20 conexões, causando timeouts. Resolvido implementando métricas de pool de conexão; alertas em utilização 80%+; rejeição graciosa de requisições não-críticas (ex: analytics) quando pool próximo de capacidade. Pools separados para conexões de leitura para relatórios.

• Failover de processador de pagamento: Stripe primário, Mercado Pago fallback. Se API Stripe inacessível (status !200), PaymentsService captura erro e retenta via Mercado Pago. Lógica circuit breaker (3 falhas consecutivas → dispara) previne cascata; recuperação manual requer endpoint /admin/circuit-breaker/reset.
• Monitoramento de pool de conexão de BD: DatadogAPM rastreia utilização de pool, tempos de espera de conexão, latências de query. Alerta disparado se utilização >80% por >5min. Resposta: escalonar horizontalmente (adicionar mais pods de serviço Checkout) ou investigar queries lentas (habilitar logging de query).
• Confiabilidade de webhook: Webhooks Discord + Meta Ads disparam assincronamente após sucesso de transação. Webhooks falhados retentados 3x com backoff exponencial (1s, 2s, 4s). Se retentativa final falha, evento logado para tabela DLQ (dead-letter queue) para investigação manual.
• Hot patching de cupom/produto: ProductsRepository cacheia resultados por 1min para reduzir hits de BD. Atualizar preço de produto ou termos de cupom requer invalidação de cache via endpoint /admin/cache/invalidate?entity=products. Mudanças propagam para réplicas dentro de 30s.
• Cron de reconciliação: Job noturno (03:00 UTC) compara ledger de transação local vs API de fatura Stripe + API de pedidos Mercado Pago. Discrepâncias (reembolso pendente, cobrança pendente, webhook faltando) dispara alerta Slack para time de pagamentos investigar.

• Validação de entrada com class-validator: DTOs (ProcessStripePaymentDto) decorados com @IsEmail(), @IsPositive(), @Length(). Pipe de validação rejeitando requisições mal-formadas cedo previne erros downstream e vetores de SQL injection.
• Queries SQL parametrizadas: Todas queries usam binding de parâmetro do cliente pg ($1, $2, etc.). Construção dinâmica de query prevenida; se precisar queries ad-hoc, requer revisão admin + mudança de código.
• Prevenção de enumeração de cupom: Cupons identificados por slug (ex: 'SUMMER20'); sem IDs inteiros sequenciais. Previne atacantes força-bruta de cupons válidos. Criação de cupom limitada ao endpoint admin com guards baseado em role.
• Chave do Stripe em variáveis de ambiente: Chave secreta nunca hardcoded ou logada. NestJS ConfigService recupera de .env; segredos rotacionados trimestralmente via integração de gerenciador de segredo CI/CD.
• Verificação de assinatura de webhook: Webhooks Stripe assinados com header sig_*; app verifica assinatura antes de processar. Previne ataques de replay e eventos webhook forjados de fontes não confiáveis.

• Fila de job assíncrono (Bull/RabbitMQ): Substituir processamento de pagamento síncrono com arquitetura baseada em fila. Requisições de pagamento enfileiradas imediatamente; workers processam transações assincronamente; webhooks atualizam frontend em tempo real.
• Lógica de retry de pagamento com backoff exponencial: Falhas transitórias (timeout de rede, rate-limit) automaticamente retentadas sem intervenção do usuário. Curva de backoff configurável por provedor.
• Contabilização baseada em ledger: Log de transação imutável (pagamento criado → processando → completado/falhou). Habilita trilha de auditoria completa, resolução de disputas e relatório financeiro sem depender apenas de APIs de terceiros.
• UI de gestão de subscrição: Portal auto-atendimento para clientes visualizarem faturas, gerenciarem métodos de pagamento, atualizarem tier de subscrição. Atualmente requer chamadas manuais de API.
• Suporte multi-tenancy: Estender arquitetura para suportar múltiplas organizações, cada uma com credenciais do processador de pagamento personalizadas, estratégias de cupom, catálogos de produto. Habilita checkout white-label.