0002 — Processar XLS (POI)

Decisão obsoleta — superada pela decisão 0026

Status: Obsoleto · Responsável: Gustavo Madruga · Atualizado em: 2026-08-19 · Decidido em: 2026-04-01

SUBSTITUÍDA pela decisão 0026 (2026-08-19): a leitura migrou de POI/SAX para FastExcel (StAX puro) para viabilizar o build native-image — o XMLBeans do POI não compila em native. O streaming (memória ~constante) foi preservado. Esta decisão fica como registro histórico.

Contexto

As planilhas de transporte chegam grandes (dezenas de milhar de linhas, arquivos de dezenas de MB — o limite de upload é 50 MB). O modo usermodel do Apache POI (XSSFWorkbook) carrega a planilha inteira em memória — estoura o heap.

Correção 2026-06-12: o texto dizia "arquivos que passam de 100 MB"; o limite real de upload é 50 MB (max-file-size). Fato incidental — a decisão (SAX) continua de pé (§1.4).

Decisão

Ler via SAX (streaming): ExcelProcessor + SheetSaxHandler + ExcelCellValue, sempre as 3 abas fixas (10 = config/período, 20 = faturamento, 30 = movimento). Limites de coluna em VarcharLimits.

Consequências

• Memória ~constante, independente do tamanho do arquivo.
• Mais código que o usermodel (handler de eventos manual), mas é o preço de suportar arquivos grandes sem OOM.
• Export JSON disponível via ProcessamentoJsonExporter.

Alternativas consideradas

• POI usermodel (XSSFWorkbook): simples, mas estoura heap nos arquivos reais do cliente. Descartado.
• Biblioteca de planilha alternativa: POI já é a stack padrão cross-project X-Adm; trocar não se justifica.