Modelagem de dados¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06
O modelo espelha as tabelas do X-Adm (base Zim) mais as tabelas de
infraestrutura da integração. O diagrama-fonte está em
anexos/modelagem.plantuml.
Convenções gerais. Toda tabela de negócio tem: a chave de negócio do
X-Adm (ex. ChaveCP, ChaveEst); um id UUID v7 surrogate (RFC 9562,
uuidv7() do Postgres 18 — ver decisão 0003);
e soft-delete (deleted, deleted_at).
Numéricos vêm do tipo Zim VastInt(n) (n decimais implícitos) → NUMERIC /
BigDecimal. Datas Zim Date(8) (AAAAMMDD) → DATE.
Espelho do ERP, dois fluxos. Todas as tabelas são do X-Adm — o Integrador
espelha o ERP. As mesmas tabelas servem duas direções: o fluxo de saída
(X-Adm → Integrador → PowerSync → apps, ex. Sul Plata; produtor = X-Adm, Chave*
já preenchida) e o fluxo de entrada (PIED → Integrador → PowerSync → X-Adm,
novo; produtor = fonte externa, Chave* vazia até o write-back). O fluxo de
entrada preenche mais colunas das mesmas tabelas e keia pela chave natural da
fonte (pied_x_ped/pied_codigo_alt/cgc_cpf — transporte PIED). Chave dupla, write-back e o princípio das
colunas de retorno em decisão 0013.
Tabelas de negócio¶
| Tabela | Chave de negócio | Papel |
|---|---|---|
CONTRATOS |
ChaveCP (saída) · PiedXPed (entrada, transporte) |
Cabeçalho do pedido; na entrada (PIED) carrega cliente, VlTot, NatOp, TpVda, … |
ITENSPED |
ChaveItem (saída) · PiedXPed+PiedCodigoAlt (entrada, transporte) |
Itens do pedido, ligados a contrato e produto; na entrada carrega Qtde/Valor/Total/TaxaFrete. |
FORMULAS |
PiedXPed+PiedCodProd (entrada, transporte) |
Fórmula (BOM) do kit: uma linha por componente (Qtde). Só entrada; sem old_id; sem colunas Chave* (o X-Adm nunca devolve chave neste fluxo); pied_formula_id = id sequencial do X-Adm gerado por nós. Ver decisão 0013. |
FONES |
CgcCpf (entrada) |
Contato do cliente (só fluxo de entrada; 1 por cliente; sem old_id). |
ITENSPEDAMX |
SeqN (BIGINT) |
Alocação de item; guarda BL, Qtde e Retirou (base do saldo de BL). |
ITPEDAMXDI |
SeqNItAmx |
Datas de desembaraço/DI do item alocado. |
ITENS / ITENSLOTE |
ChaveItemNF |
Itens da nota e por lote (ChaveLoteEst). |
ESTOQUE |
ChaveEst (saída) · CodProd (saída Thoms, ChaveEst null) · PiedCodigoAlt (entrada, transporte) |
Cadastro de produto (NomeProd + NomeProdCurto mobile); carrega EAN13/Venda/VendaPz/Saldo. Identidade = ChaveEst/CodProd; PiedCodigoAlt é código do produto NA PIED (rastreabilidade), não identidade. updated_at: ver a nota chave-versão abaixo. Ver decisão 0013. |
LOTEEST |
ChaveLoteEst |
Lote de estoque. |
NOTACOMPL |
ChaveNota |
Nota complementar; created_at (manual, ordenação cronológica) + updated_at (@DateUpdated, nullable — exceção da nota chave-versão abaixo). Base do lastchange e da ordenação de vendas. |
PROPRIEDADES |
ChaveProp (saída) · CgcCpf (entrada) |
Fornecedor/cliente; na entrada carrega endereço (Fantasia/Endereco/CEP/…); NomeProp + NomePropCurto. |
VEICULOS |
SeqVeic |
Veículo/navio (Descricao + DescricaoCurta). |
MUNICIPIO |
CodMun |
Municípios. |
TBPCOEST |
ChaveEst+período |
Tabela de preço por estoque/vigência. |
Colunas só-mobile (NomeProdCurto, NomePropCurto, DescricaoCurta) são
apelidos definidos pelo usuário no app; sincronizam de volta, nunca vão ao X-Adm.
Colunas de retorno do X-Adm. No fluxo de entrada, o X-Adm é dono das colunas
ChaveCP/ChaveEst/ChaveProp/ChaveItem/ChaveFone, CodRetorno e MsgRetorno:
elas são read-only no caminho de entrada (chegam vazias) e preenchidas só pelo
write-back (POST /api/v1/powersync), que o upsert preserva no reenvio.
Princípio: toda tabela que volta ao X-Adm (entrada) carrega CodRetorno +
MsgRetorno; numa tabela usada só na saída (Sul Plata) elas ficam sempre null.
As colunas-chave ficaram nullable (o X-Adm só as gera depois); a garantia de
cada fluxo virou crítica em runtime no XadmApplyService.
Ver decisão 0013.
Chave-versão updated_at. Toda tabela de negócio do espelho carrega
updated_at (TIMESTAMPTZ NOT NULL DEFAULT now(), índice por tabela): coluna
de controle do servidor, auto-populada por @DateUpdated (Micronaut Data) em
toda escrita de entidade (apply e write-back) e que sobrescreve qualquer valor
vindo de fora. É a ordem dos fatos que os consumidores externos varrem — o
integrador-client (PowerSync on-premise) processa os pendentes por
ORDER BY updated_at dentro de cada tabela; o tradutor Thoms faz delta-sweep por
updated_at no estoque. Exceção NOTACOMPL: ganha @DateUpdated no
updated_at, mas a coluna fica nullable (sem backfill) — o created_at
(ordenação cronológica) e o fallback COALESCE(updated_at, created_at) do
lastchange dependem de legado NULL. Tabelas
de infra (REQUEST/PUSHENVIADA/PABAST_*) ficam de fora.
Ver decisão 0014.
Tabelas de infraestrutura¶
| Tabela | Papel |
|---|---|
REQUEST |
Auditoria de cada requisição XADM (origem, tipo ETipo, json, resultado EResultado, mensagem). |
PUSHENVIADA |
Log dos pushes FCM enviados (tipo, título, conteúdo, erro). |
PABAST_EMPRESA / PABAST_SENHAS |
Empresa/credenciais legadas mantidas para o PowerSync; app/login/JWT removidos do integrador (ver decisão 0001 e esquema pAbast). |