ADR-017
Captura e processamento de e-mail em dois jobs separados
Falha de rede ao falar com o servidor de e-mail e falha de interpretação quando o formato muda são naturezas diferentes no mesmo caminho. Separá-las custou uma tabela a mais com dado pessoal e duas contagens de lead que não coincidem.
Contexto
A captura de leads acontece por e-mail: as plataformas de geração enviam a mensagem para uma caixa, e o sistema precisa baixar, interpretar e transformar aquilo em cliente. São duas naturezas de falha muito diferentes no mesmo caminho: falha de rede ao falar com o servidor de e-mail, e falha de interpretação quando o formato da mensagem muda.
Critérios que pesaram
Em ordem de peso.
- Isolar falha de rede de falha de negócio, para que uma não bloqueie a outra.
- Poder reprocessar sem reconectar. Erro de parser não deveria exigir nova ida à caixa.
- Observabilidade separada, com métrica de captura distinta da de processamento.
- Cadência própria. Buscar e interpretar não precisam da mesma frequência.
Opções consideradas
- Um job único que baixa e processa: menos peças, e qualquer indisponibilidade do servidor de e-mail congela também o processamento do que já estava baixado. Descartada.
- Dois jobs independentes, com a mensagem persistida entre eles: o e-mail bruto vira registro antes de qualquer interpretação.
Decisão
O pipeline é partido em dois jobs independentes. O primeiro conecta na caixa, baixa as mensagens novas e grava cada uma como registro pendente, com corpo em HTML e em texto preservados. O segundo pega um lote de pendentes, identifica a plataforma, extrai os dados e cria o cliente. Se o servidor de e-mail cair, o primeiro falha isolado e o segundo continua processando o que já foi baixado; se o parser errar, o e-mail já está no banco e é reprocessável sem nova conexão. Cada job tem cron próprio em configuração. O motivo registrado é literal: desacoplamento, retentativa e métricas separadas para captura e para processamento.
Consequências
As duas metades pesam igual.
Melhorou
As duas famílias de falha ficaram legíveis separadamente, e o e-mail bruto guardado virou a base de tudo o que veio depois: depuração de parser, revisão manual, vínculo com o cliente gerado e a tela de detalhe. Reprocessar um e-mail que falhou é botão de tela, não intervenção.
Piorou
Existe uma tabela a mais crescendo com corpo de e-mail (que é dado pessoal, com todas as obrigações que isso traz) e uma latência somada: o e-mail espera o ciclo do primeiro job e depois o do segundo. Também há duas fontes de contador para responder "quantos leads entraram hoje", e elas não coincidem por construção, porque nem todo e-mail capturado vira lead.
Revisitando hoje
Ainda de pé em set/2026. A decisão que mais rendeu não foi a separação em si, e sim guardar o e-mail bruto antes de interpretá-lo: sem isso, toda mudança de formato de uma plataforma teria virado lead perdido em vez de lead pendente de revisão.
Último dos quatro registros sobre a captura de leads. Os três anteriores decidiram o mecanismo; este fecha com o custo que a própria arquitetura criou.