0016 — Período do diff-aware vem da aba-10

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-12 · Decidido em: 2026-06-12

Supera a decisão 0004, cuja premissa ("o layout de transporte não expõe o período de forma confiável") era falsa.

Contexto

A decisão 0004 afirmava que o layout de transporte não traz um período confiável e que os parâmetros data/hora do upload delimitavam o DELETE seletivo do diff-aware. O código mostra o contrário, e como isso descreve um caminho destrutivo (a janela do DELETE), a correção merece registro próprio.

Decisão

Separar dois conceitos que a 0004 confundia:

• Período do relatório → vem da aba-10. O processador da aba de config lê E1 (data inicial) e F1 (data final) e lança se ausentes — o layout expõe o período de forma confiável e obrigatória. Esse período é o que delimita o DELETE seletivo do diff-aware (… WHERE dt_em BETWEEN inicio AND fim …).
• data/hora do upload → metadado. Viram data_referencia / hora_referencia em xls_processamento (quando o relatório foi gerado) e a chave de partição do object storage ({aaaa}/{mm}). Não delimitam o DELETE.

Ambos seguem obrigatórios no POST /api/xls/processar (a decisão operacional da 0004 — exigir data/hora — continua válida; muda só o porquê e o o que eles fazem).

Consequências

• O período destrutivo é determinístico (vem do conteúdo da planilha), não do que o cliente digita no upload.
• data_referencia (metadado) e periodo_inicial/periodo_final (da aba-10) são colunas distintas em xls_processamento — não confundir.
• A divergência com o Comercial cai: os dois detectam o período do conteúdo; aqui é a aba-10, lá é outro layout.

Alternativas consideradas

• Manter a narrativa da 0004 (período do upload): contradiz o código e descreve errado um caminho destrutivo. Descartado — daí esta superação.