2. Planejamento do Ciclo Analítico: Domínio Contrato¶

Objetivo¶

Garantir a previsibilidade da entrega através da quebra do domínio de Contratos em tarefas modulares, estabelecendo critérios rigorosos de validação em cada etapa da arquitetura Medallion.

Estrutura de Camadas e Entregáveis¶

Camada	Atividade Principal	Artefato Produzido	Critério de Pronto (DoD)
Extração	Mapeamento de 1993 e APIs	Scripts Python / YAML	Conexão estável e log de volume extraído.
Bronze	Ingestão Raw	Tabelas Delta (Raw)	Dados espelhados sem alteração de tipos.
Silver	Sanitização e Limpeza	Views/Tabelas Silver	Tipagem corrigida, nulos tratados, sem duplicatas.
Gold	Regras de Negócio	Tabelas de Fato/Dimensão	KPIs calculados conforme fórmulas de negócio.
Validação	Testes de Integridade	Relatório de QA / SQLs	Divergência com legado < 0.1% ou explicada.

Mapeamento de Tabelas (Fontes Legadas)¶

Para este ciclo, serão priorizados os artefatos que compõem a visão de Contrato:

Contrato: Tabela mestre de contratos.
Campanha: Tabela de campanhas vinculadas a um contrato.
Franquia: Tabela de franquias vinculadas a um contrato.
Midia: Tabela de mídias vinculadas a um contrato.

Convenções de Nomenclatura e Versionamento¶

Padrão de Arquivos: doc_[dominio]_[nome_da_pagina].md (Ex: doc_contrato_planejamento.md).
Tabelas/Views: [camada]_[dominio]_[nome] (Ex: silver_contrato_assinaturas).
Versionamento: Git Flow padrão. Commits devem referenciar o ID da tarefa (Ex: feat(contrato): add calculo ticket medio #123).

Métricas de Qualidade e Provas de Evidência¶

Para que a entrega seja aceita, os seguintes controles devem ser gerados:

Consistência de Chaves: SQL check para garantir que todo Contrato possua uma Pessoa (Aluno) válida.
Integridade Temporal: Validação de que data_fim > data_inicio.
Prova de Volume: CSV comparativo contendo: Count(Legado) vs Count(Gold).
Prints de Validação: Captura de tela do "Cockpit" comparando o resultado do DuckDB com o relatório do sistema legado.

Templates de Ciclo¶

Decisão Arquitetural (ADR)¶

Título: [ADR-00X] Título da Decisão
Contexto: Por que esta mudança é necessária? (Ex: Migração de UDF legado para SQL DuckDB).
Decisão: Qual caminho foi escolhido.
Consequências: O que ganhamos e o que perdemos.

Critérios de Aceite (Geral)¶

[x] Documentação Markdown atualizada no Cockpit.
[x] Código Python/SQL revisado e conforme o Medallion.
[x] KPIs validados por amostragem manual (mínimo 10 contratos distintos).
[x] Testes de integridade (Great Expectations ou similar) passando.