Feat/dbt docs

[bottinolucas]

feat(dbt): documentação completa dos models + camada semântica MetricFlow

O que muda

Documentação do projeto dbt em três frentes, pensada para ser consumida pelo
OpenMetadata → Neo4j → Qdrant (GraphRAG), além de servir ao time de dados.

Camada 0 — descrições (33/33 models, 87 sources)

• descriptions.yml, sources.yml e os 7 schema.yml enriquecidos a partir da
  leitura direta dos SQLs e macros: grão, ressalvas de qualidade e regras de
  negócio que antes só existiam em comentários de código.
• Ressalvas críticas agora documentadas: CPF mascarado e colisão de "miolo" em
  primeiro_acesso_contemplados; limpeza de linhas-fantasma (~R$492M) em
  contemplados_unif; ressalva recebido-vs-pago em distribuicao_cotas_pnab.
• meta.status: Active/Disabled por model — identifica os 4 que aguardam a DAG
  bbágil.
• meta.used: true/false nas sources — separa as 25 realmente lidas via
  source() das não integradas.
• Correções: nome divergente (editais_ano_por_anexo → edital_ano_por_anexo),
  parágrafo duplicado em primeiro_acesso_resumo e descrições de schema copiadas
  de outro domínio em sources.yml.

Camadas 1–4 — dbt Semantic Layer / MetricFlow (novo)

• 5 semantic models: fato fct_pagamentos_elegiveis + dimensões de agente,
  território e proponente.
• 12 métricas de negócio, incluindo as 4 cotas legais (25% / 10% / 5% / 20%)
  como razão sobre o valor com perfil — e não sobre o valor total, que
  subestima sistematicamente o cumprimento (agente sem perfil nunca entra no
  numerador).
• metricflow_time_spine — pré-requisito bloqueante do dbt Semantic Layer.
• Tags nativas config.tags: [camada, domínio] nos 33 models.

Infraestrutura

• CI: fixa dbt-core>=1.10,<1.11 no job dbt_docs, que instalava sem pin e
  pegaria a 1.12 — versão em que a especificação do Semantic Layer muda.
• 22 tests migrados para a sintaxe arguments: exigida pelo dbt 1.10.

Decisões que valem revisão

• Entidades com nomes distintos entre domínios (proponente vs
  agente_documento): os dois normalizam CPF/CNPJ de formas incompatíveis
  (máscara vs só-dígitos). Nome igual faria o MetricFlow tratá-las como a mesma
  chave e juntar bases não casáveis sem erro.
• agentes_dbt não tem métricas: toda measure exige agg_time_dimension e o
  domínio não possui coluna temporal. Ficou como dimensão pura — usar
  programa_fomento como proxy de data seria fabricar dado.
• Golds pré-agregados não viraram semantic model: distribuicao_cotas_* e
  cobertura_pagamentos foram substituídos pelas métricas. Declará-los daria
  duas respostas com grãos diferentes para a mesma pergunta.

Validação

dbt parse limpo em dbt 1.10.22 — 33 models, 67 tests, 12 metrics,
5 semantic models, zero warnings.

Não executado contra banco. O parse valida estrutura, não roda SQL. Os
expr com cast e os testes unique/relationships — incluindo o novo em
chave_municipio_uf, que protege contra fan-out na cota territorial — seguem
não verificados até um dbt build.