feat: criação da gold de instrumentos de execução das emendas

[luanaa2005]

Descrição

Adiciona o novo modelo Gold emendas_instrumentos_execucao, responsável por tratar e enriquecer a tabela numero_transferencia com a identificação padronizada dos instrumentos de execução de emendas parlamentares (Convênios, Termos de Fomento, TEDs, etc.) e seus respectivos tipos.

---

Contexto e Motivação

A tabela base de emendas apresentava limitações na identificação dos instrumentos de repasse:

1. Ruídos e inconsistências no campo numero_transferencia (valores como -9, zeros à esquerda ou strings com formatação divergente).
2. Ocorrência de números de instrumento omitidos da coluna principal, mas registrados de forma textual em campos descritivos (ne_info_complementar, ne_ccor_descricao, doc_observacao).
3. Dificuldade de relacionar repasses para Organizações da Sociedade Civil (MROSC) e descentralizações orçamentárias (TEDs) diretamente nas tabelas clássicas de convênios.

---

O que foi feito

1. Tratamento e Sanitização de Chaves (numero_instrumento):

   • Remoção de zeros à esquerda (LTRIM) e limpeza de espaços para garantir integridade no casamento de chaves.
   • Criação de um fallback via Regex para extrair o número do instrumento diretamente dos campos de texto/observação quando a coluna numero_transferencia veio nula ou com ruído (ex: -9).

2. Cruzamento Relacional Multi-Fonte:

   • convenios_consolidados (+ proposta): Resgate de instrumentos do ecossistema SICONV/Transferegov e suas modalidades detalhadas (Contrato de Repasse, Termo de Parceria, etc.).
   • **termo_fomento_consolidado
   • ted_resumo_orcamentario: Mapeamento de Termos de Execução Descentralizada entre órgãos federais e universidades.

3. Fallback por Padrão de Texto (tipo_instrumento):

   • Classificação por padrão de texto (ILIKE) para resgatar o tipo de instrumento em notas de empenho e descentralizações onde o número relacional do Transferegov não existe (ex: repasses diretos via SIPAD/UFPR).

4. Diferenciação de Regra de Negócio (numero_transferencia vs numero_instrumento):

   • numero_transferencia: Dado bruto/original exatamente como veio da fonte primária (manutenção necessária para auditoria e rastreabilidade).
   • numero_instrumento: Identificador tratado, sanitizado e validado relacionalmente (pronto para JOINs, análises e dashboards).

---

Testes e Validação da Base

Para garantir a qualidade dos dados, foram realizados testes de integridade e volumetria no ambiente PostgreSQL:

• Teste de Volumetria (Zero Fan-Out):

  • Entrada: 644 registros na tabela original.
  • Saída: 644 registros no modelo final.
  • Resultado: Zero duplicações e zero perdas de linhas.

• Distribuição da Classificação:

  • TERMO DE FOMENTO: 501 (77,80%)
  • CONVENIO: 96 (14,91%)
  • TED: 29 (4,50%)
  • NULO / NÃO CLASSIFICADO: 18 (2,80%)
  • Taxa de Cobertura: 97,20% da base devidamente classificada.

• Auditoria dos Nulos Restantes (2,8%):

  • As 18 linhas sem classificação foram auditadas individualmente. Elas correspondem a despesas diretas/contratuais operacionais do órgão (compras, contratos administrativos ou empenhos sem instrumento de repasse voluntário associado). A manutenção como NULL nesses casos evita superclassificação e falsos positivos.

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 #470

Domínio de revisão

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

Como testar / validar

dbt run --select emendas_instrumentos_execucao
dbt test --select emendas_instrumentos_execucao

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]

Muito bom!