8. Validação Analítica via SQL: Domínio Contrato¶

Objetivo¶

Provar tecnicamente a acurácia dos KPIs de Contrato antes que eles cheguem ao dashboard. O foco é garantir que qualquer divergência entre o "novo mundo" (DuckDB/Python) e o "legado" (1993) seja mapeada, explicada e aceita.

Tradução da Regra de Negócio: KPI de Volume de Contratos¶

Nome: Total de Contratos Ativos (TCA)
Regra Escrita: Contagem única de contratos que possuem status operacional 'Vigente', data de início menor ou igual hoje, data de fim maior ou igual a hoje, e que não possuem flag de 'Cancelado' ou 'Rescindido'.
Diferença Conceitual: No legado, o volume incluía contratos "Em Suspensão". Para o novo ciclo analítico, contratos suspensos são excluídos do TCA para não inflar a métrica de receita recorrente.

Queries de Validação (Ouro vs. Contraprova)¶

1. Query Oficial (Consumo da Camada Gold)¶

-- Executada no Mart de Contratos
SELECT 
    unidade,
    count(contrato_id) as total_ativos,
    sum(valor_mensal) as mrr_estimado
FROM gold_dm_contrato_performance
WHERE status_simplificado = 'Ativo'
GROUP BY 1;

2. Query de Contraprova (Direto na Bronze/Silver)¶

-- Validação granular para garantir que filtros não causaram perda de dados
SELECT 
    u.unidade_nome,
    count(DISTINCT c.id_contrato) as total_check
FROM silver_fct_contrato c
JOIN silver_dim_unidade u ON c.sk_unidade = u.sk_unidade
WHERE c.data_inicio <= current_date 
  AND c.data_fim >= current_date
  AND c.status_operacional NOT IN ('CANCELADO', 'SUSPENSO')
GROUP BY 1;

Registro de Divergências e Decisões¶

Divergência Encontrada	Causa Raiz	Classificação	Decisão Oficial
Diferença de 3% no volume da Unidade X.	Registros de 1995 com `data_fim` nula.	Limitação Técnica (Legado)	Considerar `data_fim = data_inicio + 12 meses` para registros órfãos.
Valores de Ticket Médio maiores na Gold.	Exclusão de contratos de "Bonificação" (valor zero).	Diferença Conceitual	A Gold deve refletir apenas contratos pagantes. Bonificações ficam em relatório à parte.

Testes de Agregação e Consistência¶

Consistência Geográfica: SUM(Contratos por Unidade) deve ser exatamente igual a Total Regional.
Consistência Temporal: O volume de contratos ativos em D-1 somado às Novas Matrículas (D) e subtraído dos Encerramentos (D) deve ser igual ao volume em D.
Impacto de Status: Validar se contratos "Retroativos" (assinados hoje com data de início passada) estão sendo computados corretamente no histórico.

Evidências de Prova (Snapshot)¶

Data do Teste: 2026-05-14 Amostra: Regional São Paulo Resultado Legado: 12.450 ativos Resultado Novo (Gold): 12.100 ativos Justificativa: A diferença de 350 registros refere-se a contratos "Suspensos" que o legado contava como ativos, mas a nova regra de negócio exclui conforme decisão da Diretoria (ADR-004).

Critérios de Aceite da Validação¶

[x] Query oficial e contraprova produzem resultados explicáveis.
[x] Teste de "Furo de Filtro" realizado (garantir que INNER JOINs não deletaram contratos legítimos).
[x] Definição da métrica congelada na documentação de KPIs.
[x] Stakeholder técnico validou e assinou a "Fonte da Verdade".

Documentação do KPI:

Fórmula: Count(DISTINCT ContratoID) FILTER (Status = 'Ativo')
Exclusões: Contratos de Teste, Bonificações, Cancelamentos no mesmo dia.
Granularidade: Diária (D-1).