Processamento em Lote e Arquitetura Assíncrona

Visão Geral

O sistema Grocers utiliza uma arquitetura assíncrona baseada em Azure Service Bus para processar operações em lote. Esta abordagem permite:

Processamento eficiente de grandes volumes de dados
Melhor escalabilidade e resiliência
Feedback em tempo real através de webhooks
Rastreabilidade completa das operações

Arquitetura

Componentes Principais

API de Integração
- Recebe requisições em lote
- Valida dados de entrada
- Gera identificador único (operationId)
- Envia mensagens para filas
Azure Service Bus
- Gerencia filas de mensagens
- Garante entrega das mensagens
- Suporta diferentes tipos de filas:
  - Transaction Queue: Para operações de negócio
  - Webhook Queue: Para notificações
Processadores de Mensagens
- Processam mensagens das filas
- Executam operações no banco de dados
- Geram eventos de notificação
Sistema de Notificação
- Envia atualizações via webhook
- Notifica sucesso/erro de operações
- Permite rastreamento em tempo real

Fluxo de Processamento

sequenceDiagram
    participant Cliente
    participant API
    participant ServiceBus
    participant Processor
    participant Webhook

    Cliente->>API: POST /v1/batch/{entity}
    API->>Cliente: 200 OK (operationId)
    API->>ServiceBus: Envia mensagens
    ServiceBus->>Processor: Processa mensagens
    Processor->>Webhook: Notifica progresso
    Webhook->>Cliente: Envia notificação

Recebimento da Requisição
- Cliente envia lote de dados
- API valida formato e autenticação
- Gera operationId único
Enfileiramento
- Dados são convertidos em mensagens
- Mensagens são enviadas para Azure Service Bus
- Resposta imediata com operationId
Processamento
- Mensagens são processadas assincronamente
- Operações são executadas em ordem
- Estado é mantido consistente
Notificação
- Webhook é notificado de cada operação
- Cliente recebe atualizações em tempo real
- Erros são reportados detalhadamente

Endpoints Disponíveis

Os seguintes endpoints suportam processamento em lote:

Rastreamento de Operações

Cada operação em lote recebe um operationId único que permite:

Rastrear progresso da operação
Identificar mensagens relacionadas
Correlacionar notificações
Investigar erros

Exemplo de Ciclo de Vida

Início

{
  "operationId": "54d6a979-5f62-4e17-9d4c-dbd9f5ede403",
  "status": "started",
  "totalItems": 100,
  "processedItems": 0
}

Progresso

{
  "operationId": "54d6a979-5f62-4e17-9d4c-dbd9f5ede403",
  "status": "processing",
  "totalItems": 100,
  "processedItems": 50,
  "successCount": 48,
  "errorCount": 2
}

Conclusão

{
  "operationId": "54d6a979-5f62-4e17-9d4c-dbd9f5ede403",
  "status": "completed",
  "totalItems": 100,
  "processedItems": 100,
  "successCount": 95,
  "errorCount": 5,
  "completedAt": "2024-02-04T12:30:00Z"
}

Tratamento de Erros

O sistema implementa várias estratégias para garantir resiliência:

Retry Automático
- Tentativas automáticas em caso de falhas temporárias
- Backoff exponencial entre tentativas
- Máximo de 3 tentativas por operação
Dead Letter Queue
- Mensagens que falham após todas as tentativas
- Armazenadas para análise posterior
- Podem ser reprocessadas manualmente
Notificação de Erros
- Erros são reportados via webhook
- Incluem detalhes específicos do problema
- Permitem ação corretiva pelo cliente

Boas Práticas

Tamanho do Lote
- Recomendado: máximo 1000 itens por requisição
- Dividir lotes grandes em menores
- Considerar volume de dados por item
Monitoramento
- Acompanhar notificações de webhook
- Verificar status das operações
- Manter registro dos operationIds
Tratamento de Erros
- Implementar retry no cliente
- Armazenar itens com erro
- Reprocessar apenas itens falhos

Visão Geral​

Arquitetura​

Componentes Principais​

Fluxo de Processamento​

Endpoints Disponíveis​

Rastreamento de Operações​

Exemplo de Ciclo de Vida​

Tratamento de Erros​

Boas Práticas​