Pular para conteúdo

03 — Resiliência: backoff, fila destravada e os avisos do ERP

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

Entregue em v0.0.6–v0.0.10 (agosto de 2026), com o ajuste do teto em v0.0.12.

Escopo

A fundação provou o fio; o que faltava era comportamento sob falha. Três defeitos de campo dão a medida: lote que falhava reprocessava ~1×/s martelando o ZIM; status ficava preso na fila local até alguém reiniciar o cliente; e as críticas que o X-Adm grava para o usuário sumiam, porque num daemon não há tela.

O que foi construído

  • Backoff exponencial quando o ciclo deixa pendência (falha geral, retorno parcial ou 9XX reprocessável): piso 1s, dobrando, teto 15 min (era 60 min — longo demais para MDF-e, que é sensível a tempo). O gatilho do próprio eco é descartado: a write-back do status volta como mudança do PowerSync e reprocessaria o mesmo lote. Dado novo da nuvem fura o backoff e o zera — o item preso entra no mesmo arquivo do novo.
  • Vigia do write-back: se a fila local fica presa mais de 20s, reconecta. Contorna um bug do SDK que não re-tenta o upload ao voltar do offline — medido no e2e, vale para o cliente Kotlin e para o Rust.
  • Avisos do X-Adm (dRels3): após o programa ZIM, em qualquer desfecho, o cliente lê as críticas que o ERP gravou, registra no log e no GlitchTip, e apaga o arquivo. Conflito de concorrência foi depois excluído do alerta (o lote retenta sozinho; era ruído sem ação possível), mas segue no log.
  • Eco das linhas no log: cada linha escrita no envio e cada linha lida do retorno saem no log entre |pipes|, em nível INFO — dá para conferir o que o ZIM recebeu e devolveu sem entrar no modo debug.
  • Marcador de handshake opcional na leitura do retorno final: o ZIM escreve Iniciou Zim no handshake e depois limpa o arquivo, regravando o final sem ele. Exigi-lo fazia o 006 de sucesso ser lido como lote inválido — e o MDF-e já baixado reprocessava sem parar.
  • Higiene de operador: caminhos do ZIM com espaço aceitos, erro de config local sem abrir incidente, e log em UTF-8 (console e arquivo) com o rodar.bat pondo o console em UTF-8.

Riscos que ficam

O backoff protege o ERP, mas não conserta dado: 1XX é terminal por contrato. É o que a etapa 05 ataca por outro caminho — impedindo que o lote saia incompleto.