📚 Pré-requisitos Teóricos: Este projeto prático aplica os conceitos essenciais ensinados na Especialização em Backend com PHP e Laravel. Recomendamos sua leitura para aprofundamento em mensageria assíncrona, workers e idempotência.

O Processamento de Pagamentos & Filas no Redis com Laravel aborda o desenvolvimento de uma infraestrutura financeira resiliente, capaz de absorver picos massivos de transações sem bloqueio de I/O. Utilizando Laravel 11, Redis Queues, webhooks do Stripe com validação de assinatura e garantias rígidas de idempotência, o sistema assegura tolerância a falhas e processamento garantido de pagamentos.

🏛️ Arquitetura do Pipeline Financeiro Assíncrono

O diagrama abaixo apresenta o fluxo desacoplado desde a notificação do webhook do Stripe até o processamento no worker daemon:

📁 Estrutura de Pastas Padronizada

A base de código segue o padrão canônico com nomenclatura anti-colisão:

catalogo_projetos/backend_php_03_queues_redis_stripe/
├── api-laravel/              # Backend de processamento assíncrono em Laravel 11
│   ├── app/
│   │   ├── Http/
│   │   │   └── Controllers/
│   │   │       └── StripeWebhookController.php # Endpoint com resposta imediata
│   │   ├── Jobs/
│   │   │   └── ProcessarPagamentoJob.php       # Job assíncrono despachado no Redis
│   │   └── Models/
│   │       └── Pedido.php
│   ├── config/
│   │   ├── queue.php         # Configuração de drivers de fila (Redis)
│   │   └── horizon.php       # Monitoramento de throughput e workers
│   └── composer.json         # Dependências: predis/predis, stripe/stripe-php
├── assets/                   # Galeria de diagramas visuais e arquitetura
│   └── arquitetura_laravel_queues_stripe.svg
└── index.md                  # Especificação executiva e Padrão Ouro

🧑‍💼 Engenharia de Software & Requisitos

1. Histórias de Usuário (US)

2. Requisitos Funcionais (RF)

3. Requisitos Não-Funcionais (RNF)

4. Diagrama de Casos de Uso

flowchart TD
    subgraph Atores
        STR["Stripe Webhook Gateway"]
        WRK["Worker Daemon (Redis)"]
        SRE["Operador / SRE"]
    end

    subgraph "Processador de Pagamentos (api-laravel)"
        UC1["Validar Assinatura HMAC do Stripe"]
        UC2["Despachar Job para Fila Redis"]
        UC3["Verificar Idempotência do Evento"]
        UC4["Atualizar Pedido em Transação Atômica"]
        UC5["Gerenciar Falhas na Dead-Letter Queue"]
    end

    STR --> UC1
    UC1 --> UC2
    WRK --> UC3
    UC3 --> UC4
    WRK --> UC5
    SRE --> UC5

5. Matriz de Rastreabilidade (RTM)

🛠️ Implementação do Job Assíncrono (api-laravel/app/Jobs/ProcessarPagamentoJob.php)

<?php

namespace App\Jobs;

use App\Models\Pedido;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;

class ProcessarPagamentoJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 3;
    public array $backoff = [15, 60, 300];

    public function __construct(
        public string $eventId,
        public string $pedidoId,
        public float $valor,
        public string $statusPagamento
    ) {
        $this->onQueue('payments');
    }

    public function handle(): void
    {
        Log::info("Iniciando processamento assincrono do evento: {$this->eventId}");

        // Garantia de idempotencia no nivel de banco
        $eventoProcessado = DB::table('stripe_events')
            ->where('event_id', $this->eventId)
            ->exists();

        if ($eventoProcessado) {
            Log::warning("Evento duplicado detectado e descartado: {$this->eventId}");
            return;
        }

        DB::transaction(function () {
            // Atualizar status do pedido
            Pedido::where('id', $this->pedidoId)->update([
                'status' => 'pago',
                'valor_confirmado' => $this->valor,
            ]);

            // Registrar processamento para assegurar idempotencia
            DB::table('stripe_events')->insert([
                'event_id' => $this->eventId,
                'pedido_id' => $this->pedidoId,
                'created_at' => now(),
            ]);
        });

        Log::info("Pagamento do pedido {$this->pedidoId} confirmado com sucesso.");
    }
}

🚀 Roteiro de Execução

1. Iniciar Redis e Aplicação Laravel

cd catalogo_projetos/backend_php_03_queues_redis_stripe/api-laravel
composer install
php artisan migrate

2. Iniciar o Worker de Filas do Redis

php artisan queue:work redis --queue=payments --tries=3

3. Simular Disparo de Webhook via Stripe CLI

stripe trigger checkout.session.completed

🎯 Matriz de Checkpoints de Entrega