0003 — Contrato canônico JSON Python↔Java¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-11 · Decidido em: 2026-04-03
Contexto¶
Este serviço Java substitui um fluxo Python que já rodava em produção. A migração só é segura se o resultado do parse Java for idêntico ao do Python para os mesmos arquivos — caso contrário, divergências entram silenciosas.
Decisão¶
Definir um JSON Schema canônico do resultado do processamento (período +
faturamentos + movimentos + metadados): schema-processamento-xls.json. Os
testes de paridade rodam arquivos reais por fixtures (src/test/resources/
fixtures/transporte-YYYYMMDD/input.xlsx + resultado-python.json golden) e
comparam a saída Java contra o resultado do Python.
Consequências¶
- Regressão de parsing é detectável automaticamente, não por inspeção visual.
- O schema (
docs/dev/schema-processamento-xls.json) é o contrato canônico do resultado do processamento: serve de referência para os testes de paridade e é publicado como contrato de input/export no níveldev/da doc.
Correção 2026-06-12: o texto dizia que o schema "não é documentação publicada"; ele é publicado em
docs/dev/(referência não-prosa, §2/§5). Fato incidental — a decisão (contrato canônico p/ paridade) segue (§1.4). - Cobre vários meses (uma fixture por período) com asserção forte (golden).
Alternativas consideradas¶
- Validação manual/visual: frágil e não repetível. Descartado.
- Reescrever sem rede de paridade: risco alto de divergir do legado sem ninguém perceber. Descartado.