Pular para conteúdo

0002 — Caminho robusto (servidor always-on)

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-11 · Decidido em: 2026-07-09

Contexto

O pré-projeto da integração PIED → X-Adm avaliou dois caminhos:

  1. Caminho 1 — integração simples: cliente Java CLI que puxa a API REST sob demanda/agendado e entrega arquivos JSON ao X-Adm. Foi aprovado primeiro e validado em produção como poc-pied-simples (contrato da API comprovado com token real em 2026-06-17).
  2. Caminho 2 — robusto: servidor always-on na nuvem com webhook (tempo real) + poll REST + staging Postgres + entrega desacoplada via PowerSync até um cliente Java junto ao ERP. Foi desenhado em detalhe no poc-pied (ARQUITETURA.md, servidor/SPEC.md).

O caminho 1 cumpre o essencial, mas depende de acionamento pelo lado X-Adm, não tem tempo real e não deixa trilha em banco para análise/reprocessamento contínuo.

Decisão

A diretoria aprovou o caminho 2 (robusto) em 2026-07-09 (Marcelo Garabeli). Adotado neste projeto (maxsul-pied, publicado em pied.maxsul.xadm.biz), reaproveitando dos POCs o que já foi comprovado:

  • do poc-pied-simples: o contrato validado da API (endpoints, envelope, paginação 1-based com limite 50, parada em página vazia) e a estratégia incremental por ?lastUpdateAfter só para pedidos (ADR 0002 de lá);
  • do poc-pied: os princípios do servidor — persistir raw ANTES de processar, webhook responde 200 rápido sem processamento síncrono, nunca escrever síncrono no ERP (entrega via staging + PowerSync), e a constatação de que o webhook sozinho não cobre tudo (o poll REST é obrigatório, não só rede de segurança).

A implantação é em fases (ver decisão 0001): fase 1 captura raw; fase 2 transform + entrega.

Consequências

  • Banco compartilhado, donos separados. O Integrador (instância Maxsul) e o maxsul-pied conectam no mesmo Postgres. O Integrador é dono das tabelas espelho do X-Adm (contratos, propriedades, fones, itensped, estoque); o maxsul-pied é dono das tabelas PIED (pied_webhook_*, pied_request_*, pied_produto, pied_cliente, pied_pedido).
  • Escrita cruzada só por contrato REST. O maxsul-pied grava nas tabelas do Integrador pelo mesmo PUT/DELETE /api/v1/xadm que o agente on-premises do X-Adm já usa — não por SQL direto. Preserva a serialização (ReentrantLock), a auditoria (request) e o soft-delete/revive do Integrador. O PowerSync lê as tabelas do Integrador.
  • Um serviço always-on a operar (Coolify, healthcheck, Postgres compartilhado) — custo de operação aceito em troca de tempo real e trilha completa em banco.
  • O cursor incremental sai do estado.json (arquivo, caminho 1) para a tabela pied_cursor.
  • O poc-pied-simples permanece como está: referência validada e fallback operacional; este projeto não o substitui até a fase 2 estar entregue.
  • Os 4 componentes da solução (este app, Integrador Maxsul, PowerSync, cliente Java no ERP) estão descritos na Documentação Completa.

Alternativas consideradas

  • Continuar só com o caminho 1: rejeitado para o alvo final — sem tempo real, dependente de acionamento manual/agendado do lado ERP e sem trilha em banco.
  • Webhook sem poll: rejeitado — lacunas conhecidas de eventos (produtos não têm webhook; alterações de frete/responsável não disparam evento), conforme o blueprint do poc-pied.