O ERP do cliente nunca é consultado ao vivo

ADR-003 — O ERP do cliente nunca é consultado ao vivo

Data: 2026-08-09 (virada standalone) · Situação: vigente

Contexto

O sistema de origem consultava o ERP do cliente ao vivo: cadastro de cliente, limite de crédito, histórico de aprovação, anexos, pedidos, parcelas — tudo em consulta síncrona a um Oracle, muitas vezes autenticando como o próprio usuário logado. Havia telas inteiras dedicadas a isso.

Isso amarrava o produto a um ERP, a uma topologia de rede e à disponibilidade de um sistema de terceiros. Como SaaS vendido a várias empresas, com ERPs diferentes, não funciona.

Decisão

Nenhuma consulta ao ERP em tempo de request. Cada organização recebe dados por sincronização para o espelho sync_<slug> (ent-bancos), por três modos previstos:

Modo	Como	Estado
C — API	O sincronizador do cliente empurra lotes em /sync/v1/* com ent-sync-token	Existe (mod-sync-ingest)
B — Views	O cliente expõe views SQL e um conector puxa	Não existe
A — Agente local	Instalável no cliente, empurra pela API	Não existe

Se o ERP cair, o AppStock continua operando com o que tem. Só para de sincronizar.

Por quê

• O AppStock é o motor comercial, não um satélite. A jornada precisa rodar mesmo com o ERP fora do ar — é o que se está vendendo.
• Desempenho previsível. Dashboard e listagem consultam Postgres local, não Oracle remoto.
• Integração vira contrato, não acoplamento: o mesmo espelho serve qualquer ERP que saiba preenchê-lo. É a base dos “kits por ERP”.

Consequências

Boas: dashboards rápidos, produto demonstrável sem ERP nenhum (é o que a organização demo faz), e a possibilidade de vender para quem tem ERP que ninguém conhece.

Ruins, e são a maior parte do trabalho que resta:

• Escrever de volta virou um problema aberto. Toda ação que precisa chegar ao ERP — cliente novo, crédito, invoice, pedido, viagem, DANFE — está desligada e responde 501. A fila de writeback (outbox) foi apagada e ainda não foi reconstruída. São 24 endpoints.
• O dado tem latência. O que o vendedor vê é a última carga, não o agora. Não há indicação disso em tela nenhuma.
• A qualidade do produto passou a depender do sincronizador do cliente. Sem cursores, sem reconciliação e sem painel real, ninguém sabe se a carga veio inteira. Ver flx-primeira-carga.
• O contrato ainda não é neutro. O espelho e as consultas dependem de chaves de campo customizado herdadas do CRM de origem (NomVen__c e semelhantes), inclusive dentro do sync_template.sql que gera o banco de cada organização nova. Enquanto isso não for neutralizado, o kit plug-and-play por ERP não fecha.

O que isso apagou do produto

As telas que liam e gravavam no ERP ao vivo não voltam — não são lacuna. O que era leitura ao vivo virou espelho; o que era “Salvar no ERP” vira a fila de saída. Ficaram órfãs três funções de negócio que moravam naquelas telas (manutenção de parcelas, cadastro de representantes, pedidos de transferência) e precisam virar entidade nativa.