Inteligência operacional de delivery

01 — Contexto

Operações de delivery distribuídas entre várias unidades produzem eventos continuamente: pedidos, transições de estado, cancelamentos completos, cancelamentos parciais, motivos, horários e evidências.

O dado existia, mas permanecia fragmentado nas ferramentas da operação. O objetivo deste projeto foi construir uma camada própria capaz de responder rapidamente: o que aconteceu, onde, por que, com que frequência e quem precisa saber agora?

Este é um projeto privado. Empresas, unidades, pessoas, endpoints, credenciais, payloads originais e regras confidenciais foram removidos ou abstraídos deliberadamente.

02 — Problema

O fluxo anterior era reativo:

Evento → Consulta → Interpretação → Comunicação → Ação

Em escala, isso aumentava a latência, fragmentava o contexto e dificultava enxergar padrões. A proposta foi inverter a lógica:

Evento → Captura → Normalização → Classificação → Persistência → Análise → Alerta

O sistema não deveria apenas registrar ocorrências. Deveria reduzir a distância entre o problema acontecer, alguém perceber e a operação conseguir agir.

03 — Descoberta da fonte

Antes de construir dashboards, foi necessário entender como os dados trafegavam entre as aplicações da operação. A investigação mapeou eventos disponíveis, estados de um pedido, campos correlacionáveis, eventos repetidos e diferenças semânticas entre ocorrências estruturalmente parecidas.

Esse foi um ponto central do trabalho: consumir dados não é o mesmo que entender o que eles significam. Um cancelamento no início do ciclo pode representar uma situação completamente diferente de um cancelamento depois do preparo.

04 — Ingestão e contrato interno

A camada de ingestão funciona como fronteira entre a plataforma de origem e o restante da aplicação. Quando existe uma integração apropriada, o evento entra diretamente por ela; em outros cenários, mecanismos autorizados observam os dados disponíveis ao ambiente operacional e encaminham somente o necessário.

Fonte operacional
       ↓
Camada de ingestão
       ↓
Validação
       ↓
Modelo interno
       ↓
Pipeline operacional

O sistema externo possui seu contrato; a aplicação possui o seu. Conceitualmente, o modelo interno reúne identificador do evento e do pedido, unidade, tipo, horário, motivo, origem, itens, metadados de evidência e status de processamento.

Essa separação protege regras, relatórios e notificações contra mudanças no payload externo. Quando a integração muda, o adaptador muda primeiro.

05 — Pipeline de processamento

Cada evento passa por responsabilidades explícitas:

Evento bruto
    ↓
Validação
    ↓
Normalização
    ↓
Identificação
    ↓
Deduplicação
    ↓
Classificação
    ↓
Persistência
    ↓
Regras de negócio
    ↓
Agregações
    ↓
Alertas / Dashboard / Relatórios

A separação tornou o processamento mais simples de evoluir e depurar. Também tornou visíveis os pontos em que um evento pode ser descartado, reprocessado ou encaminhado para tratamento posterior.

06 — Cancelamentos completos e parciais

Cancelamentos integrais são classificados com pedido, unidade, momento, categoria, motivo, origem, contexto operacional, estado anterior e existência de evidências quando essas informações estão disponíveis.

Cancelamentos parciais exigem outro grão de análise. O pedido pode continuar ativo enquanto um ou mais itens apresentam ocorrência:

Pedido
 ├── Item A
 ├── Item B ← ocorrência
 ├── Item C
 └── Item D

Essa granularidade permite investigar itens recorrentes, categorias concentradas e mudanças de comportamento que uma contagem de pedidos não revelaria.

07 — Idempotência e deduplicação

Em sistemas orientados a eventos, receber o mesmo evento duas vezes não pode significar executar duas vezes. Sem identidade e deduplicação, o pipeline poderia criar registros duplicados, inflar métricas e enviar alertas repetidos.

Mesmo evento recebido novamente
        ↓
Evento reconhecido
        ↓
Nenhuma nova consequência operacional

Essa garantia é especialmente importante quando integrações externas precisam de retries ou quando eventos podem ser observados por mais de uma estratégia de entrada.

08 — Persistência e organização

Os eventos normalizados são armazenados em estrutura relacional. O modelo separa grupos operacionais, unidades, pedidos, eventos e ocorrências de itens. Assim, a mesma informação pode ser consultada em diferentes níveis:

• detalhe de um pedido;
• desempenho de uma unidade;
• visão consolidada de um grupo.

O histórico também separa duas perguntas diferentes: o que está acontecendo agora? e o que vem acontecendo ao longo do tempo? Sem persistência, a solução seria apenas um mecanismo de alerta.

09 — Alertas e roteamento

Quando uma ocorrência relevante é processada, uma mensagem estruturada pode ser enviada ao grupo responsável. O roteamento identifica a unidade, resolve seu agrupamento, determina o destino e gera uma comunicação com contexto suficiente para ação.

Evento → Unidade → Agrupamento → Destino → Mensagem → Envio

O princípio é simples: automação útil não envia tudo para todos. Cada equipe recebe apenas o que pertence ao seu escopo, reduzindo ruído e aumentando a chance de resposta.

10 — Métricas e análise

Além dos alertas individuais, o sistema consolida janelas de tempo para produzir uma visão operacional. Entre os cortes possíveis estão pedidos processados, ocorrências por tipo, distribuição por unidade, concentração por horário, itens recorrentes e evolução histórica.

A taxa de ocorrência é analisada em relação ao volume:

Taxa de ocorrência = ocorrências relevantes / volume de pedidos × 100

Normalizar evita que volume absoluto conte uma história errada. A análise temporal e por item também ajuda a separar um caso isolado de uma concentração que merece investigação de processo, capacidade, abastecimento ou treinamento.

O sistema aponta onde investigar; não transforma correlação operacional em causalidade automaticamente.

11 — Push e pull

O dashboard administrativo complementa a mensageria com uma visão de investigação. O modelo combina duas formas de consumo:

• Push: o sistema envia ocorrências que exigem atenção.
• Pull: a pessoa consulta histórico, tendências e recortes quando precisa investigar.

Essa combinação evita tanto depender de alguém procurando cada ocorrência quanto tentar transformar cada evento em uma notificação urgente.

12 — Workers, agendamentos e falhas

Captura e processamento principal permanecem separados de tarefas que podem ser mais lentas: agregações, verificação de regras, relatórios e comunicação externa. Workers e rotinas agendadas executam essas etapas sem bloquear o caminho crítico.

Integrações falham, conexões caem e payloads mudam. Por isso, o sistema registra eventos recebidos, processados, descartados, duplicidades, falhas de persistência, falhas de comunicação e tentativas posteriores.

Processar evento
     ↓
   sucesso ─────→ continuar
     │
     └ falha
         ↓
      registrar
         ↓
   tratar / repetir

Automação confiável precisa ser observável também quando deixa de funcionar.

13 — Privacidade by design

O projeto aplica minimização de dados. Quando uma ocorrência possui evidências, a camada analítica pode registrar que existem referências associadas sem transportar o conteúdo sensível:

evento X → possui evidência → possui N referências → ocorrência Y

Tokens, cookies, credenciais, identificadores reais, dados pessoais, endpoints privados e payloads originais não fazem parte deste case. Segredos ficam separados do código por configuração de ambiente.

14 — Stack e trade-offs

• TypeScript / Next.js — integração, regras e interface administrativa.
• PostgreSQL — entidades relacionais, eventos e histórico operacional.
• Workers / Scheduler — tarefas assíncronas, agregações e relatórios periódicos.
• APIs HTTP — comunicação entre componentes e adaptadores de entrada.
• Mensageria — distribuição roteada de alertas aos canais apropriados.

A arquitetura foi mantida modular sem introduzir uma plataforma distribuída antes de haver necessidade real. Um broker de eventos, processamento de stream e uma camada analítica dedicada são evoluções possíveis para maior volume e menor latência, não requisitos artificiais do recorte atual.

15 — Resultado

O que começou como acompanhamento de cancelamentos evoluiu para uma camada de inteligência entre o sistema transacional e a operação:

                EVENTOS
                   ↓
               INGESTÃO
                   ↓
              NORMALIZAÇÃO
                   ↓
              PERSISTÊNCIA
                   ↓
          ┌────────┴────────┐
          ↓                 ↓
     TEMPO REAL          HISTÓRICO
          ↓                 ↓
       REGRAS           AGREGAÇÕES
          ↓                 ↓
      ALERTAS            MÉTRICAS
          ↓                 ↓
     OPERAÇÃO           DASHBOARD
          └────────┬────────┘
                   ↓
                DECISÃO

O resultado mais importante é temporal: reduzir a distância entre algo acontecer e alguém perceber. Depois, reduzir a distância entre perceber um caso isolado e entender que existe um padrão.