Glossário do projeto¶

Vocabulário do domínio da integração que este app usa. Termos da plataforma X-Adm (Forgejo, Coolify, Garage…) não são redefinidos aqui — linkam para o glossário da plataforma.

Sistemas e sincronização¶

X-Adm: ERP de mesa (base Zim) onde todos os dados de negócio nascem; sistema-fonte da integração.
X-Adm Integração Java: Agente on-premises que lê os arquivos JSON exportados pelo X-Adm e os encaminha via REST/HTTPS (com retry) ao Integrador.
Integrador: Este servidor Micronaut/Java; recebe REST, persiste no Postgres, emite push (FCM) e alimenta o PowerSync. Uma instância por cliente.
PowerSync: Motor de sincronização self-hosted (Journey Apps) que acompanha o WAL do Postgres e replica para o SQLite local do app; habilita o offline-first.
lastchange: Endpoint público de checagem de "banco parado": MAX(COALESCE(updated_at, created_at)) de notacompl.

Contrato REST¶

XADM (endpoint /api/v1/xadm): Contrato REST PUT/DELETE que o ERP usa para empurrar mudanças de tabela; sempre HTTP 200, resultado no corpo JSON.
Origem: Código da rotina que gerou a requisição: do X-Adm (PPEDAMX, PPEDIDO, PBLDI, PNOTAI, PNOTAD, PCSTPROD, PREQUIS) ou do fluxo de entrada PIED (INT-PIED); a whitelist KNOWN_ORIGENS decide o que vai ao Sentry.
Bearer estático: Token fixo (INTEGRADOR_API_TOKEN) que protege /api/** — não é JWT. O nome antigo API_BEARER_TOKEN não é mais lido (sem fallback).
Heartbeat: Sinal de vida que cada instalação do integrador-client manda (versão, fluxos, hostname) no startup e a cada 60 min a POST /api/v1/heartbeat. O Integrador não o grava: carimba o cliente_id e o repassa ao central-backend, que acompanha as instalações e alerta o silêncio (contrato).
CLIENTE_ID × CLIENTE: CLIENTE é o nome de exibição do cliente (Maxsul, Sul Plata Trading do Brasil); CLIENTE_ID é o identificador dele no central-backend (maxsul), usado no repasse do heartbeat. Um não substitui o outro — por isso o CLIENTE_ID não tem fallback.

Domínio e tipos¶

BL: Bill of Lading; identificador de embarque. "Saldo dos BLs" (relatório 30 do X-Adm) é uma tela central no mobile.
ChaveCP / ChaveProp / ChaveEst / ChaveItem / ChaveNota / ChaveLoteEst: Chaves de negócio compostas do X-Adm para contrato, propriedade (fornecedor), estoque (produto), item de pedido, nota e lote de estoque.
VastInt(n): Tipo numérico escalado do Zim com n decimais implícitos; mapeia para NUMERIC / BigDecimal (ex. VastInt(3) → NUMERIC(15,3)).
Zim: Motor de banco sob o X-Adm; seus tipos (VarAlpha, Date(8), Char(n)) são espelhados no esquema da integração.
UUID v7: UUID ordenado no tempo (RFC 9562, uuidv7() do Postgres 18); migrado do v4, valor antigo preservado em old_id (migrations V14–V16).
Soft-delete (deleted, deleted_at): Exclusão lógica: DELETE marca deleted=true; um POST com a mesma chave restaura (migration V7).
NomeCurto (NomeProdCurto / NomePropCurto / DescricaoCurta): Apelidos definidos pelo usuário para produtos/clientes/veículos; vivem só no app, editados no mobile, nunca escritos no X-Adm.
pAbast (pabast_empresa / pabast_senhas): Tabelas legadas de empresa/credencial mantidas para o PowerSync; app, login e JWT foram removidos do integrador (decisão 0001).
Fluxo de saída / Fluxo de entrada: As duas direções do espelho do X-Adm. Saída: X-Adm → Integrador → PowerSync → apps (original, ex. Sul Plata; produtor = X-Adm, Chave* preenchida). Entrada: fonte externa (PIED / INT-PIED) → Integrador → PowerSync → X-Adm (o dado volta ao ERP; Chave* vazia até o write-back). Mesmas tabelas, mais colunas (decisão 0013).
Chave dupla: Estratégia de upsert que resolve a linha pela Chave* do X-Adm quando o produtor a fornece (saída) e pela chave natural da fonte (xPed/pied_codigo_alt/CgcCpf) quando ela chega vazia (entrada). No estoque, a saída resolve por ChaveEst ou, quando ele é null (Thoms), por CodProd.
CodProd (identidade do produto): Identidade do produto no X-Adm quando ChaveEst chega vazio (instância Thoms): versão virtual (substring) do ChaveEst. Gravado como recebido no PUT de saída — sem processamento sobre a chave (decisão 0013).
PiedCodigoAlt (transporte): Código do produto na PIED (ex-codigo_alt), armazenado só para rastreabilidade e como chave natural de correlação do fluxo de entrada. Não é a identidade do produto no espelho — o espelho é cópia fiel do X-Adm, cuja identidade de estoque é ChaveEst/CodProd.
updated_at (chave-versão do estoque): Timestamp em estoque (V21) auto-populado por Micronaut Data (@DateUpdated) em toda escrita de entidade (save/update), por qualquer escritor que passe pelo repositório (apply, tela admin, API, write-back PowerSync). É a versão que o tradutor WebStorm-ecom (Thoms) usa para idempotência. Sem dirty-check — bumpa em qualquer update de entidade. O @Query cru de nome_prod_curto não passa por entidade e não bumpa. Ver decisão 0013.
Retorno do X-Adm (write-back): As colunas Chave*/CodRetorno/MsgRetorno que o X-Adm gera para cada linha do fluxo de entrada e devolve pelo POST /api/v1/powersync; são read-only no caminho de entrada (a fonte não as escreve; o upsert as preserva). Toda tabela que volta ao X-Adm carrega CodRetorno/MsgRetorno; na saída ficam sempre null.
fones: Tabela de contato do cliente (só fluxo de entrada; chave natural cgc_cpf); um contato por cliente. Sem old_id (tabela nova).

Baixa de MDF-e (macro Sascar)¶

MDF-e: Manifesto Eletrônico de Documentos Fiscais; agrupa as NF-e/CT-e de uma viagem. No espelho vive na tabela mdf (cabeçalho) + mdfcompl/mdfitens/nfmdf/nfcomplmdf/ fretes/nfeevento (contexto). Ingerida pelo MDFE_PUT (Origem:PMDFE).
situacao_baixa: Coluna própria do Integrador na mdf (não vem do X-Adm): ATIVO (vigiada), BAIXA (encerramento solicitado — comando pendente), ERRO. Distinta do NFEEVENTO (fiel ao X-Adm, só leitura). Ver baixa-mdfe-sascar.
cod_retorno (MDF-e): Sinal do comando de baixa que o fluxo ENCERRA_MDFE do integrador-client observa na mdf: 000 pendente (setado pelo callback), 006 executado (write-back do client), 1XX/9XX erro. Mesmo contrato de retorno do fluxo de entrada PIED (V18).
watch (Sascar): POST destilado do Integrador ao int-sascar (/api/integrador/mdfe/watch) dizendo quais MDF-e vigiar (status=aberto) e quando tirar do conjunto ativo (status=encerrado). O int-sascar nunca vê o JSON cru do ZIM — recebe status/destino já interpretados.
macro Sascar: Sinal que o motorista dispara no rastreador Sascar ao fim da viagem; o int-sascar o detecta e chama o callback POST /api/sascar/encerramento do Integrador, que grava a baixa.
ENCERRA_MDFE: Fluxo dXpEnvio do integrador-client (no ZIM) que lê o comando de baixa (situacao_baixa=BAIXA/cod_retorno=000) pelo PowerSync e encerra a MDF-e no ERP, escrevendo cod_retorno=006 de volta. Vive fora deste repo.

Infraestrutura¶

FCM: Firebase Cloud Messaging; push para 4 tópicos (2 por empresa: bl_liberado_*, nota_venda_emitida_*).
Nuvem Wiechert: Hospedagem/infra de terceiros (Wiechert Suporte Técnico) onde rodam o Integrador, o Postgres e o PowerSync.