Pular para conteúdo

0010 — Detecção automática do tipo de relatório

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

Correção 2026-09-08: eram 7 tipos quando esta decisão foi tomada; hoje são 9 — COMPRAS entrou com a decisão 0017 e COTA_PETROBRAS com a 0019. O corpo abaixo fica como registro do que se decidiu em 2026-04-10; a contagem saiu do título justamente por envelhecer. Lista viva: o enum processing/TipoArquivo.

Correção 2026-07-16: a rota citada no Contexto mudou — hoje o upload é POST /api/xls/processar, um .zip com os .xlsx do lote. Fato incidental: a decisão (detectar o tipo em vez de pedir ao cliente) segue valendo e ficou ainda mais central, já que o servidor detecta o tipo de cada entrada do zip. O período continua vindo do conteúdo. Estado atual no livro.

Contexto

Ao longo do mês o cliente comercial envia 7 tipos de relatório diferentes: RELATORIO18, MARGEM_CONSOLIDADA, MARGEM_DIA, META, META_FERNANDO, POSTOS e TRR. Forçar o cliente a informar o tipo (na URL, num header, num campo) cria uma classe de bugs evitável — tipo errado significa linhas gravadas na tabela errada. O upload (POST /api/xls/processar) também não exige período: ele vem do conteúdo.

Decisão

Um processing/ArquivoDetector (@Singleton) recebe os bytes do .xlsx + o nome e devolve um TipoArquivo (enum), de forma determinística e ordenada por prioridade (primeira condição satisfeita ganha): META_FERNANDO → POSTOS → TRR por coluna/sheet do cabeçalho; RELATORIO18 → MARGEM_CONSOLIDADA → MARGEM_DIA → META por padrão de nome. Cada tipo tem um {Tipo}Processor dedicado em processing/, todos lendo via ExcelSheetReader (SAX) e persistindo via BulkUpsert diff-aware.

  • Nada bateu (tipo desconhecido) → BadRequestException → HTTP 400 na recepção; não entra em xls_processamento. (O status IGNORADO é outra coisa: tipo detectado, mas período ≤ a data mínima 10/08/2025 — ver etapa 01.)
  • Nome iniciando com ~$ (temporário do Excel) ou # (revisão interna) → BadRequestException (HTTP 400), sem entrar em xls_processamento.

Consequências

  • UX do cliente: envia qualquer arquivo, o app deduz o tipo — menos erros de integração.
  • Estender é ritual conhecido: novo valor no enum + regra no detectar() (com teste em ArquivoDetectorTest) + {Tipo}Processor + registro no ProcessamentoTransactionalHelper.
  • Diverge do irmão Transporte, que lê 3 abas fixas (10/20/30) — domínios diferentes; lá o formato é estável, aqui são 7 relatórios distintos.

Alternativas consideradas

  • Parâmetro tipoArquivo na URL/header: joga a responsabilidade no cliente e abre a porta para gravar na tabela errada. Descartado.
  • 3 abas fixas (modelo Transporte): não modela 7 relatórios com layouts distintos. Descartado por não caber no domínio comercial.