Etapa 03 — Conformidade Python↔Java¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-14

Rede de segurança da transição: o processador Java (etapa 01) substitui scripts Python que rodaram anos. Esta etapa prova, arquivo a arquivo, que os dois produzem o mesmo banco — pela idempotência da etapa 02, o que importa é o estado final, não a ordem de escrita.

1. Contexto e escopo¶

Durante a coexistência Python/Java, uma regressão silenciosa (arredondamento, ordem de processamento, edge case de dado real) escreveria dado errado no BI sem ninguém perceber. A conformidade compara os dois lados pelo golden-master offline (ConformidadeTest): fixtures versionadas provam a paridade no CI, sem Python vivo.

Dentro do escopo: o formato canônico do snapshot Python; o ConformidadeTest offline; a política de fixture anonimizada; TestXlsxFactory.

Fora do escopo: conformidade em produção (ver seção 5); auto-correção de divergências; comparação reversa (Java→Python).

2. Componentes e modelo de dados¶

O formato do resultado-python.json é a fonte de verdade do schema do snapshot: {tipo, nome_arquivo, dados: {…}}, onde dados tem uma lista por tabela (filial, cliente, vendedor, produto, movimento, custo_inventario, …) cujas chaves variam por tipo detectado.

flowchart TB
    fx[fixtures/&lt;tipo&gt;-YYYYMMDD/<br/>input.xlsx + resultado-python.json]
    ct[ConformidadeTest]
    fx --> ct
    ct -->|processa input.xlsx| javadb[(Postgres de teste)]
    ct -->|compara| fx

Fixtures (src/test/resources/fixtures/<tipo>-YYYYMMDD/): input.xlsx (planilha real anonimizada) + resultado-python.json (snapshot que o Python produziu). Cada fixture roda contra o Postgres de teste com as tabelas limpas.
TestXlsxFactory: monta .xlsx sintéticos nos testes.

3. Fluxo¶

ConformidadeTest carrega cada fixture, processa input.xlsx pelo processador Java e valida que o conteúdo do banco bate com resultado-python.json. É o gate de regressão do CI.

O oráculo Python não existe mais: os resultado-python.json versionados continuam válidos (o teste os lê de disco), mas fixture nova desse tipo não pode mais ser gerada. Paridade de tipo novo usa a caracterização do reader (ReaderCaracterizacaoTest), que congela o comportamento vigente como oráculo — ver decisão 0020.

4. Configuração e política de fixtures¶

O ConformidadeTest é integração (@IntegracaoDocker) e roda no ./gradlew test/check: ./gradlew test --tests "*ConformidadeTest*". Pré-requisito: Docker rodando — sem ele a classe é pulada com ERROR no log.
A fixture golden-master nasce anonimizada: nomes, CNPJs e valores sensíveis trocados por sintéticos preservando shape e resultado esperado — "repo privado" não é anonimização. Manter dado real exige justificativa declarada, não silenciosa.
Receita de captura e status por família de fixture: javadoc de ConformidadeTest.

5. Frente de produção abandonada¶

O desenho original previa uma segunda frente: cada XLSX processado pelos dois lados teria o pedaço de banco que ele contribuiu comparado em produção, por um endpoint que recebia o snapshot do Python. Ela não foi construída — o projeto de Automação que hospedava o Python foi desativado antes, e sem o lado Python não há o que comparar em produção. A etapa fecha com o golden-master offline como entrega.

6. Riscos¶

Fixture desatualizada após mudança de layout do cliente → nova fixture (ou caracterização do reader) no mesmo PR do ajuste no parser (etapa 01).
Dado real vazando numa fixture → anonimização obrigatória na captura; auditado.

Correção 2026-09-14: a etapa descrevia como entregue um endpoint de conformidade em produção que nunca foi construído; o texto passou a registrar o abandono dessa frente, e a etapa fecha com o golden-master offline.