Qualidade de Dados e Auditoria do Tratamento

1.2A fotografia da base

Toda avaliação de qualidade descreve um instante. Sem dizer qual, a conclusão perde validade: a base muda todo dia, e um defeito corrigido ontem continuaria sendo reportado. Os dados abaixo são lidos do manifesto de ingestão, gerado na mesma execução que gravou os arquivos.

1.3Dimensões verificadas

O diagnóstico cobriu doze dimensões. Registrar as que passaram é tão importante quanto registrar as que falharam: sem elas, o leitor não sabe se a dimensão foi verificada e passou ou se simplesmente não foi olhada.

1.4Achados, com a leitura técnica

1.5A camada Silver: o que foi aplicado

Sete tabelas têm regra de tratamento; as outras 11 são copiadas como vieram, porque no Bronze já estavam conformes e transformar o que não precisa é criar diferença sem motivo.

1.5.1 As regras

As funções de transformação vivem em transformacoes.py, isoladas de banco, arquivo e DataFrame. Cada uma faz uma coisa, recebe e devolve valor simples, e tem teste unitário com o caso fácil e o caso que costuma quebrar. A regra que governa todas é normalizar para comparar, preservar para exibir.

1.5.2 Onde o tratamento tocou

190.991 células alteradas em 5 colunas de 3 tabelas. O denominador correto aqui é a célula, não a linha: o tratamento age em campo, e dividir por linha inflaria a proporção em tantas vezes quantas forem as colunas. Sobre as 190.194.916 células do domínio operacional, a proporção é 0.1004%, ou 1 célula em cada 995.

1.5.3 As regras que rodaram e não corrigiram nada

13 colunas passaram por regra de tratamento sem ter uma única célula alterada, porque já vinham conformes da origem. Isso é registrado por honestidade metodológica (o pipeline não infla o número de correções) e porque essas regras são defesa, não conserto: existem para o dia em que a origem mudar de formato, e são o que impede que essa mudança quebre o Gold sem aviso.

1.6Auditoria do tratamento

Um pipeline de limpeza falha de dois jeitos, e o segundo é muito pior. Não corrigir o que devia é visível: o defeito continua lá, alguém reclama. Corrigir o que não devia é invisível: o número fica bonito, o relatório fecha, e o dado está errado. Esta seção foi desenhada para pegar o segundo caso.

1.6.1 O grão foi preservado?

18 de 18 tabelas mantiveram a contagem exata de linhas. 0 colunas foram perdidas. As únicas colunas novas são _processado_em, técnica, e chave_endereco, derivada e aditiva.

Grão preservado é o que garante que qualquer número do Gold pode ser aberto até o registro individual. É também o que separa uma camada Silver de uma camada de relatório: se o tratamento já entregasse o dado agregado, todo relatório novo voltaria ao Bronze e a rastreabilidade morreria no meio do caminho.

1.6.2 Alguma ausência foi criada ou destruída?

A única divergência é deliberada, e vale como exemplo do critério. Em ocorrencia.observacao havia texto livre com -, N/A e sem informacao, que é ausência disfarçada de conteúdo: mantê-los faria qualquer agrupamento exibir - como se fosse uma categoria real de ocorrência. Converter para ausência revela a falta; preencher a ausência esconde a falta.

Verificação complementar: 0 valores de ausência disfarçados de texto (nan, none, null, -) sobraram nas 18 tabelas do Silver.

1.6.3 Os achados que precisavam sobreviver intactos

1.6.4 O incidente que originou esta seção

1.6.5 O tratamento é idempotente?

As 7 regras foram reaplicadas sobre o próprio Silver: nenhuma célula muda. Sem essa propriedade, reprocessar uma carga (o que acontece o tempo todo, por falha de rede, correção de defeito ou dado atrasado) produziria resultado diferente do anterior, e ninguém saberia qual dos dois é o certo.

A propriedade não é automática. A eleição da grafia canônica poderia facilmente não ser idempotente: se o desempate fosse a ordem de leitura do arquivo, ou se houvesse qualquer sorteio, duas execuções elegeriam vencedores diferentes e o mesmo endereço mudaria de nome a cada carga. Por isso o desempate final é alfabético, que é ordem estável e independe de como o dado chegou.

1.7Antes e depois, por campo

O caso de São Paulo ilustra o mecanismo: no Bronze existiam as grafias SAO PAULO, Sao Paulo, SÃO PAULO, São Paulo; no Silver existe uma só, com acento.

Duplicidade de endereço: marcada, não fundida

O pipeline tem informação suficiente para fundir os cadastros e escolhe não fazê-lo. Saber que dois cadastros são o mesmo lugar é diferente de ter autoridade para eliminar um deles. Marcar entrega ao cliente as duas coisas: o problema quantificado e a liberdade de decidir. Fundir entregaria só o resultado, sem volta, porque os pedidos antigos referenciam o registro que seria eliminado.

1.8Limitações e como reproduzir

Limitações declaradas

• O diagnóstico descreve a carga de 2026-08-27. Cargas posteriores podem trazer defeitos novos, e os defeitos de origem (Q1, Q2, Q3, Q5) voltam a cada carga enquanto não houver validação na entrada do sistema.
• A eleição de grafia canônica usa apenas os próprios dados, sem lista externa de municípios. Se a base inteira escrever uma cidade errada, ela continua errada, só que uniforme.
• A duplicidade de endereço é detectada por logradouro, cidade e UF. Duplicata com logradouro escrito de forma substancialmente diferente não é capturada.
• O tratamento cobre texto e formato. Não cobre veracidade: um CEP válido no formato mas errado para o endereço não é detectável sem fonte externa.

Reprodução

Todo número deste documento sai da leitura das camadas no momento da emissão. Para reproduzir:

1. uv run python -m logistica_otif_mlops.pipelines.bronze
2. uv run python -m logistica_otif_mlops.pipelines.silver
3. uv run pytest · 89 testes
4. uv run python -m logistica_otif_mlops.relatorios · regera estes dois documentos