feat: enriquecimento Silver de Faturas com Dados Cadastrais de Contratos

[luanaa2005]

Descrição

Este PR implementa a modelagem Silver contratos_faturas.sql no dbt. O objetivo principal é realizar o cruzamento direto entre a base de faturas e a base de contratos do Compras GOV utilizando a chave contrato_id.

A modelagem garante que todas as faturas sejam preservadas (via LEFT JOIN) e enriquecidas com as informações cadastrais essenciais do contrato associado, seguindo o padrão de modelagem adotado no IPEA.

---

Alterações Realizadas

1. Criação do Modelo Silver

• Arquivo: models/contratos_dbt/silver/contratos_faturas.sql
• Materialização: table

2. Estrutura do Código SQL & Justificativas Técnicas

• Manutenção Integral da Tabela de Faturas (f.*):

  • Escolha: Optou-se por projetar f.* em vez de explicitar colunas individuais.
  • Justificativa: Algumas colunas específicas presentes em outros schemas (ex: IPEA) não existem de forma isolada na estrutura da tabela de faturas do MIR (como subelemento ou id_empenho, que vêm serializados em JSON). O uso de f.* previne erros de compilação/execução no dbt e garante a preservação de 100% dos atributos nativos da fatura.

• Tratamento da Chave de Junção (contrato_id):

  • Escolha: Aplicação de trim(cast(... as text)) em ambos os lados da condição ON:

    ON trim(cast(f.contrato_id as text)) = c.contrato_id_key

  • Justificativa: Previne divergências de tipo (text vs integer) e falhas de junção motivadas por caracteres de espaço em branco ou nulos, garantindo o correto emparelhamento entre o ID numérico do Compras GOV na fatura e o ID do contrato.

• Propagação de Dados Cadastrais do Contrato:

  • Escolha: Inclusão dos campos numero_contrato, contrato_processo, fornecedor_cnpj_cpf_idgener, fornecedor_tipo, fornecedor_nome, objeto_contrato e unidades_requisitantes.
  • Justificativa: Provê o contexto cadastral necessário (quem contratou, o que foi contratado, qual o processo e quem forneceu) sem poluir a tabela de faturas com métricas/saldos financeiros do contrato (que pertencem exclusivamente à entidade contrato).

• Garantia de Não-Perda de Faturas (LEFT JOIN):

  • Escolha: Uso estrito de LEFT JOIN.
  • Justificativa: Atende ao critério de aceitação de manter a integridade da base de faturas, registrando faturas "órfãs" (sem contrato na base) com atributos de contrato nulos sem descartá-las do histórico.

---

Tipo de mudança

• Nova funcionalidade / pipeline
• Correção de bug ou inconsistência de dados
• Refatoração de modelo DBT
• Documentação
• Infraestrutura / CI
• Outro: ___

Issues relacionadas

Closes #456

Domínio de revisão

• GCES / OSS
• IPEA
• MIR
• MCid
• MinC
• OSS
• Múltiplos domínios: ___

Como testar / validar

dbt run --select contratos_faturas

Evidências

Checklist

• Título do PR segue Conventional Commits
• Issue relacionada foi referenciada
• Testes/lint foram executados ou a ausência foi justificada
• Testes DBT adicionados/atualizados, se aplicável
• Documentação atualizada, se aplicável
• Sem dados sensíveis ou credenciais no código
• Branch atualizada com upstream/main ou origin/main
• Revisores automáticos por domínio foram solicitados pelo GitHub ou justificados no PR

[TiagoSBittencourt]

Bom de mais