0011 — Coordenação de lotes e notificação agregada

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-16 · Decidido em: 2026-04-10

Correção 2026-07-16: o mecanismo decidido aqui continua em uso — o ConjuntoLoteService ainda registra o progresso em xls_conjunto_lote e dispara uma única notificação Telegram agregada ao fim do lote. O que mudou é a origem do conjunto_id e do total: eles deixaram de ser campos opcionais declarados pelo cliente no POST e passaram a ser derivados do conteúdo pelo servidor. Hoje a ingestão é uma porta única POST /api/xls/processar que recebe um .zip (o zip é o lote): o id é zip-<sha256 do zip> e o total é o número de entradas .xlsx. Com isso o lote virou a regra, não a exceção — não existe mais o caso "upload avulso sem os campos" descrito nas Consequências. Estado atual no livro.

Contexto

O cliente comercial não envia um arquivo por vez: manda um pacote de N planilhas (os vários relatórios do período). Cada upload é independente e assíncrono, então, sem coordenação, a equipe receberia N notificações Telegram soltas — ruído — e não teria um marco claro de "o lote inteiro terminou".

Decisão

O POST /api/xls/processar aceita dois campos opcionais: conjunto_id (identificador do lote) e conjunto_total (quantos arquivos o lote tem). O service/ConjuntoLoteService registra o progresso na tabela xls_conjunto_lote e dispara uma notificação Telegram agregada quando o N-ésimo arquivo do conjunto chega. Sem esses campos, cada arquivo é processado normalmente, de forma independente.

Consequências

• Uma notificação por lote em vez de N — sinal limpo de "terminou" para a equipe.
• Os campos são opcionais: uploads avulsos continuam funcionando sem mudança.
• A tabela xls_conjunto_lote é metadado do processador (xls_*): não sincroniza via PowerSync; o cliente não a edita.
• Recurso exclusivo do Onpetro — o irmão Transporte não recebe pacotes de N arquivos, então não tem coordenação de lote.

Alternativas consideradas

• Uma notificação por arquivo: ruído proporcional ao tamanho do lote e sem marco de conclusão. Descartado.
• Agregar por janela de tempo (debounce): frágil — depende de timing de chegada, não do total real do lote; um arquivo atrasado quebraria a contagem. O conjunto_total explícito é determinístico. Descartado.