Glossário do projeto¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06

Vocabulário próprio desta integração. Termos gerais da plataforma estão no glossário da plataforma X-Adm.

X-Adm: ERP fornecido pela X-Adm ao cliente Thoms, onde ocorrem o cadastro e a precificação dos produtos. É a origem dos dados desta integração.
Parceiro (WebStorm): WebStorm (https://www.webstorm.com.br) — empresa que desenvolve e opera o e-commerce da Thoms e expõe a API REST (POST /sync/erp) que recebe os dados dos produtos. É o destino dos dados; dá nome ao app deste repo (webstorm-ecom.thoms.xadm.biz) e ao prefixo das tabelas (webstorm_ecom_*).
Integrador (hub): Nuvem em int.thoms.xadm.biz que recebe os dados de produto/estoque que o X-Adm posta (modelo ERP), grava o log de requests de entrada e consolida a réplica. É do projeto integrador (repo xadm/integrador-server, doc em https://docs.xadm.biz/aplicacoes/integrador-server/): app Java/Micronaut multi-tenant (um deploy Coolify por cliente; int.thoms.xadm.biz é o da Thoms). Aqui é referenciado.
Réplica (do X-Adm): Banco, mantido pelo integrador, com o estado consolidado de produto/estoque que o X-Adm envia. É réplica parcial (só o que a integração usa), não uma cópia do ERP inteiro.
Tradutor: App Micronaut dedicado enxuto em webstorm-ecom.thoms.xadm.biz que lê a réplica direto no db_thoms, mapeia para o contrato do parceiro, faz o POST e grava a webstorm_ecom_request. Acionado por webhook + sweep (ver termos). É o mini-projeto deste repo e a casa de futuras consultas de preço/produto (decisão 0003).
Requests de entrada: Store, no integrador, com o log de cada request que o X-Adm posta (auditoria da ponta de entrada).
webstorm_ecom_request: Tabela do tradutor que grava cada POST de saída ao parceiro e a resposta recebida, mais o controle de idempotência (versão/estado já enviado) — auditoria da ponta de saída. Prefixo webstorm_ecom_* = tabela do tradutor no banco compartilhado (ver db_thoms).
db_thoms: O único banco Postgres compartilhado pelo integrador e pelo tradutor. Fronteira: cada app tem Flyway próprio (history dedicada) para as migrations não colidirem; as tabelas do tradutor são prefixadas webstorm_ecom_*; a réplica é do integrador (o tradutor a lê, nunca a migra).
Webhook (A) / sweep (D): Como o integrador aciona o tradutor. Webhook (A): o integrador faz um POST numa URL do tradutor ("produto X mudou") ao consolidar — baixa latência, Bearer + @Retryable. Sweep (D): um @Scheduled no tradutor varre a réplica por versão > última enviada — rede de segurança (padrão Outbox/Polling Publisher: o próprio banco é a fila). Os dois chamam o mesmo código; a idempotência evita duplicidade. Substituem o PowerSync do desenho anterior (decisão 0003).
Carga inicial: Exportação de todos os produtos do X-Adm em ProdutosSite.csv, enviada por e-mail ao parceiro para importação em massa. Semeia a base do e-commerce uma vez; independe do fluxo contínuo.
Preço à vista: Preço do produto para pagamento à vista (com desconto). Mapeia para preco_desconto no contrato do parceiro (decisão 0001).
Preço a prazo: Preço do produto para pagamento a prazo (preço cheio). Mapeia para preco_cheio no contrato do parceiro (decisão 0001).
EAN: Código de barras global do produto (GTIN/EAN-13). Chave natural usada pelo parceiro para localizar o produto na base dele (decisão 0002).
Código X-Adm: Identificador interno do produto no X-Adm (CODIGO no CSV; codigo_erp no contrato do parceiro).
ProdutosSite.csv: Arquivo CSV que o X-Adm gera com os produtos (11 colunas: CODIGO;NOME;ATRIBUTO;VALOR;ESTOQUE;STATUS;PESO;PROMOCAO;INI PROMOCAO;FIM PROMOCAO;EAN13). Origem da carga inicial e referência das colunas do de-para (ver modelo de dados).
STATUS (X-Adm): Coluna do ProdutosSite.csv: 1 = produto ativo com saldo em estoque; 0 = inativo, zerado ou que ficará negativo por pedido pendente.