Glossário do projeto¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-04

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

PIED: Plataforma em que a empresa de painéis solares da Maxsul registra produtos, clientes e pedidos. Expõe API REST (Authorization: Bearer) e webhooks de eventos.
X-Adm: ERP de mesa usado pela Maxsul para a operação fiscal — o destino final dos dados (fase 2).
Caminho robusto (caminho 2): Arquitetura com servidor always-on (este app) + staging + PowerSync + cliente Java junto ao ERP, em oposição ao caminho simples (CLI poc-pied-simples). Ver decisão 0002.
Landing (captura raw): Tabelas pied_webhook e pied_rest: os payloads da PIED gravados crus (jsonb), antes de qualquer transformação. Fonte para análise da API e para o transform da fase 2.
Webhook: POST /webhook/pied — a PIED empurra eventos (order.created, budget.updated...) em tempo real. O cadastro do endpoint no painel da PIED é manual.
Poll: Job agendado que consulta ativamente a API REST da PIED, paginando produtos, clientes e pedidos e gravando cada página crua em pied_rest.
Envelope: Forma comum das respostas REST da PIED: {error, data: {items, totalItems}}. Página além do fim retorna HTTP 200 com items vazio — a condição de parada da paginação.
lastUpdateAfter: Parâmetro ?lastUpdateAfter=AAAA-MM-DD que filtra pedidos por data de atualização no servidor. Só funciona em pedidos — produtos e clientes são sempre varridos por inteiro.
Cursor: Data persistida em pied_cursor usada como lastUpdateAfter da próxima rodada de poll. Avança para a data do início da rodada apenas em caso de sucesso.
Toggle: Chave liga/desliga por variável de ambiente (PIED_WEBHOOK_HABILITADO, PIED_POLL_HABILITADO, PIED_INTEGRACAO_HABILITADA). Permitem entrar em produção por partes.
Fase 1 / Fase 2: Fase 1 = este MVP (só captura raw). Fase 2 = transform para o formato X-Adm + entrega via PowerSync até o ERP. Ver decisão 0001.
PowerSync: Serviço que replica o Postgres de staging para o SQLite local do consumidor (offline-first, watch reativo) — mecanismo de entrega da fase 2 (ps.maxsul.xadm.biz).
Integrador: Plataforma de integração da casa X-Adm (int.maxsul.xadm.biz na instância Maxsul) — staging/API que recebe o estado desejado para o ERP na fase 2.
Console operador: Tela única /console de operação da fase 2 (absorveu o antigo /inspetor+/fila). Dirige cada pedido pela máquina de estados real (pied_pedido.status) e expõe, por pedido, o de-para dry-run, o stepper e as ações liberadas pelo estado (puxar, enfileirar, enviar, atualizar, reenviar, re-normalizar) + sync de clientes. Interativo em STAGING, monitor em PRODUCAO.
Máquina de estados (entrega): Coluna pied_pedido.status — fonte única do progresso de um pedido na entrega ao X-Adm: CAPTURADO → NA_FILA → ENVIANDO → ENVIADO → CONFIRMADO, com os ramos ERRO_XADM (rejeição do X-Adm; 1XX terminal / 9XX reprocessável) e ERRO (falha de transporte, reenfileirável).
Dois eixos de status (integração × PIED): Um pedido tem dois status independentes, exibidos em colunas separadas na lista do painel — não confundir: Status Integração é o nosso lado (o pedido ainda não foi levado ao X-Adm = "Pedidos em aberto"); Pagamento PIED é o lado da PIED (lá o mesmo pedido já pode constar Pago). Um pedido "em aberto" (integração) e "Pago" (PIED) ao mesmo tempo é o caso normal — é justamente ele que os botões Importar/Dispensar tratam.
Status amigável (bucket) — eixo integração (coluna "Status Integração"): Tradução do status técnico da entrega para 4 rótulos voltados ao usuário final no painel (/, /pedidos/{code}). Fonte única: painel/StatusBucket. Mapa:

Bucket (UI)	Estados internos
Pedidos em aberto	`CAPTURADO`, `NA_FILA` sem prontidão
Enviando ao X-Adm	`NA_FILA` pronto, `ENVIANDO`, `ENVIADO`, `ERRO`
Importados no X-Adm	`CONFIRMADO`, `IMPORTADO_MANUAL` (dispensado na home, ou "Importado manualmente" após uma falha)
Falha ao importar	`ERRO_XADM`

Desconhecido/branco → Pedidos em aberto. ERRO (falha de transporte, transitória) cai em Enviando ao X-Adm; só ERRO_XADM (rejeição do X-Adm, final) é Erro.

Prontidão (2026-09-04) — NA_FILA é o único status cujo bucket não sai só do nome: pedido capturado por webhook nasce sem o invoice (Faturamento, que só vem no REST) e o PushService o segura na fila até o enriquecimento sob demanda buscá-lo (decisão 0017). Sem invoice ele volta para Pedidos em aberto (está esperando dado); com invoice, é Enviando ao X-Adm (está a caminho). Os botões Importar/Dispensar seguem só no CAPTURADO — o preso já está na fila. Ver decisão 0006 (vocabulário revisado pela spec .ia/003).

Pagamento PIED — eixo PIED (coluna "Pagamento PIED"): Estado do pedido na PIED, ortogonal ao status de integração. Duas infos na mesma coluna: o pagamento traduzido (payment.status → painel/PagamentoPied) e o estágio cru (deal_status). Mapa do pagamento:

Rótulo (UI)	`payment.status` cru
Pago	`received`
Solicitado	`requested`
Não solicitado	`notRequested`
Parcial	`partial`
Cancelado	`cancelled`
—	vazio / desconhecido

received é o que dispara o Gate (pagamento recebido) (abaixo). O deal_status é o texto do estágio do pedido na PIED (ex. "Finalizado"), exibido cru.

Painel colaborador: Telas abertas do usuário Maxsul, chrome limpo da marca XADM: GET / (dashboard — tiles de status + lista de pedidos) e GET /pedidos/{code} (detalhe — timeline + dados + itens). Quase read-only (os botões Importar/Dispensar da home, para pedido em aberto já pago, e Importado manualmente — mais o Re-Importar, só quando parte do pedido ainda está pendente —, para pedido em Falha); as ações de operação ficam no console operador (/console). A home de diagnóstico (cards) vive em /homedev.
Gate (pagamento recebido): Regra que decide quando um pedido entra na fila de envio (Maxsul, 2026-08-07): a transição do payment.status para received — tínhamos o pedido não-pago e chegou um update que o marca pago. Detectada por evento no upsert de pied_pedido (payment_status/payment_status_anterior). Pedido que aparece já-pago na 1ª captura NÃO dispara (pode ser antigo). Manual no console (Enfileirar) exige payment_status='received'. dealStatus deixou de ser o gate.
Resgate da 1ª captura já paga: Exceção cercada ao Gate acima (decisão 0023, depois do apagão de webhook de 18/09/2026): quando o pedido é visto já pago na primeira captura — webhook perdido, poll REST o alcança depois de pago — não há transição a testemunhar e ele encalha em CAPTURADO. Com o resgate ligado, o upsert enfileira direto, cercado pelo orderCreated da PIED: piso (PIED_GATE_PRIMEIRA_CAPTURA_DESDE, data de ativação; vazio = desligado, o default) e janela de novidade (7 dias). Regra em GatePrimeiraCaptura. Não é relaxamento do Gate: só cobre quem nunca teve transição a ser vista.