Billing, CRM, produto e analytics
SCD na origem e acumulador para o que se apaga
Estado de qualquer entidade em qualquer dia
MRR, comissão, health score e agente de IA
O que resolve
- MRR, carteira e status de meses passados deixam de mudar com o estado de hoje.
- Uso e eventos que a fonte apaga ficam guardados.
- Uma sincronização que falha não leva o histórico junto.
Perguntas de negócio que responde
Faça estas perguntas ao seu agente quando o caso estiver pronto.
O que você precisa
- Billing, CRM e produto conectados na Nekt
- SCD Type 2 ligado nas tabelas que mudam no lugar
- A lista dos campos de negócio que importam acompanhar
O que você recebe
- Tabelas versionadas com início e fim de vigência
- Fotos diárias de uso e de métricas calculadas
- Um mapa de cobertura com a data de início de cada histórico
- Um agente de IA que responde como estava em uma data
Onde ativar
MRR, clientes ativos e movimentos de qualquer mês lidos do estado daquele mês.
Dono do mês e carteira por dia de corte, para NDR e variável sem disputa.
Responde como estava uma conta numa data, dizendo de onde vem o dado e desde quando há histórico.
Ligar o SCD é uma configuração por tabela. Os acumuladores de fontes que se apagam pedem notebook. O custo maior é começar tarde. O detalhado traz as regras de negócio, as armadilhas e o teste de aceitação. Ou mande tudo direto para o seu agente com o MCP da Nekt.
Billing, CRM e produto guardam só o estado de agora. A assinatura que estava past_due ontem hoje aparece active, o dono do deal que vendeu já é outro, o uso de 30 dias do analytics é sobrescrito a cada sincronização, e eventos do Stripe e coleções com TTL somem depois de algumas semanas. Sem histórico gravado não há MRR de meses passados, comissão pelo dono do mês nem tendência de uso. E uma sincronização completa que falha no meio pode apagar meses.
Como costuma ser feito, e a regra
Cada linha é um erro que já aconteceu na prática.
Ative o SCD Type 2 da Nekt nas tabelas que mudam no lugar: assinaturas e itens do billing, clientes, deals e empresas do CRM, contas e planos do banco do produto. Cada mudança vira uma versão com _available_from, _available_until e _deleted. O que veio antes não volta: para MRR, reconstrua pelas faturas; para dono e etapa, pelo histórico de propriedades do CRM.
Eventos do Stripe ficam disponíveis por cerca de 30 a 40 dias, coleções do MongoDB com TTL apagam documentos (cerca de 45 dias num caso real) e gráficos do Amplitude e planilhas de métricas devolvem só uma janela de 30 dias sobrescrita. Acumule numa tabela própria por dia e id, com merge, reprocessando os últimos dias a cada execução para que uma falha se recupere sozinha.
Transformação SQL na Nekt sobrescreve a tabela inteira a cada execução. Para fotografar MRR do dia, carteira ou uso agregado, use notebook com mode merge, ou uma query que lê a própria saída e mantém todos os dias anteriores, substituindo só o dia corrente.
Antes de gravar, a rotina recusa resultado vazio ou muito menor que o anterior, salvo autorização explícita. Antes de uma sincronização completa de uma fonte grande, tire uma cópia congelada: um full sync que falhou no meio já apagou quase cinco meses de eventos de uma tabela.
No billing, a maior parte das versões novas só avança o ciclo de cobrança ou troca a última fatura. Para contar mudança de status, plano, quantidade, preço ou aviso de cancelamento no fim do ciclo (cancel_at_period_end), compare o campo de negócio com a versão anterior e conte só quando ele mudou.
O estado do dia D é a versão vigente em D+1 00:00 de Brasília, ou seja, D+1 03:00 UTC. Com várias versões no mesmo dia, vale a última. Rode a sessão em UTC e converta só no corte, uma vez.
Para carteira, NDR e comissão, o dono de um mês passado é o dono vigente num dia combinado (por exemplo, dia 5, dando ao time do dia 1 ao 4 para transferir contas). Trocas depois do corte ficam marcadas como troca no meio do mês, sem mudar o dono de base. O mês corrente usa o dono mais recente.
Quando o SCD não foi ligado a tempo, recupere etapa, valor e dono pelo histórico de propriedades do HubSpot (propertiesWithHistory, uma entrada por mudança com valor, data e origem). Se o conector não traz a propriedade de que você precisa, um script temporário busca na API, marcado como temporário e com data de remoção.
Passado reconstruído por faturas, logs ou backfill fica marcado com a origem. Modelos e indicadores usam só o que estava disponível no fim do período anterior (point-in-time). Num caso real, atributos de contrato reconstruídos por backfill contaminaram um modelo de churn e tiveram de ser retirados.
Mês fechado é lido da foto congelada. Uma reclassificação histórica é feita uma vez, documentada com data e motivo, e não se repete a cada execução. Correção posterior entra como ajuste no mês em que foi descoberta.
O que guardar e como
Cada tipo de dado de SaaS tem um jeito de não perder o passado.
Definições
Armadilhas que já aconteceram
Uma sincronização completa de eventos de produto falhou no meio e apagou quase cinco meses da tabela.
Cópia congelada antes de qualquer full sync de fonte grande.
Uma execução sobrescreveu a tabela de fotos diárias e três semanas tiveram de ser reconstruídas à mão.
Query auto-referente que só troca o dia corrente, e trava contra resultado vazio.
A coleção de conversas do produto apagava documentos com mais de 45 dias, e o componente de tendência nunca pôde ser calculado.
Acumulador diário por cliente desde o primeiro dia.
A planilha de métricas trazia só os últimos 30 dias, sobrescritos todo dia; não havia como saber se 45% de adesão vinha subindo de 20% ou caindo de 80%.
Foto semanal ou diária acumulada por conta.
O conector não trazia o histórico do dono dos deals, e a carteira por mês ficava com o dono de hoje.
Script temporário pela API, marcado para remoção quando o conector trouxer o campo.
Atributos de contrato preenchidos por backfill vazaram informação posterior para o treino de um modelo de churn.
Features só com o que existia no fim do período anterior.
Teste de aceitação
O caso está pronto quando todos os itens passam.
- Para 20 assinaturas, o status na data D lido do histórico bate com a fatura ou com o relatório do billing daquele dia.
- Cada entidade tem exatamente uma versão vigente em qualquer instante, sem sobreposição de vigências.
- A foto diária tem uma linha por entidade e dia desde a primeira coleta, e as lacunas aparecem listadas.
- Rodar a rotina duas vezes no mesmo dia não muda as fotos dos dias anteriores.
- Uma execução com resultado vazio falha sem gravar.
Pacote para o agente
Cole no Claude, ChatGPT ou outro cliente com o MCP da Nekt conectado.
Histórico de estado - Para qualquer pergunta sobre o passado, use a tabela versionada ou a foto diária, nunca a tabela de estado atual. - Estado na data D = versão com _available_from até D+1 03:00 UTC e _available_until nulo ou posterior. Vigente hoje = _available_until nulo e _deleted falso. - Versão nova não é mudança de negócio. Mudança = status, plano, quantidade, preço, cancel_at_period_end, dono ou etapa diferente da versão anterior. - Dono do mês = dono vigente no dia <dia de corte> do mês; no mês corrente, o atual. - Cobertura: <tabela> tem histórico desde <data>. Antes disso, o dado é reconstruído e está marcado; diga isso na resposta. - Dia sem foto é lacuna, não zero. - Mês fechado vem da foto congelada; não recalcule. Exceções por cliente: - <cliente>: o histórico de dono dos deals vem de um script temporário até <data>. - <cliente>: reclassificação única feita em <data> pelo motivo <motivo>; não reaplicar.
Construa no meu workspace Nekt o caso "Histórico de estado" seguindo as regras em https://academy.nekt.com/industrias/saas/historico-de-estado.md. 1) Encontre as tabelas de origem e confirme as colunas usadas pelas regras. 2) Crie uma transformação no grão indicado aplicando todas as regras. 3) Rode o teste de aceitação e me mostre o resultado de cada item. 4) Crie o context document do caso no workspace, com as exceções dos meus clientes em aberto para eu preencher.
Variações
Congelamento e desativação de clientes reconstruídos em períodos (início e fim) a partir de eventos de automação, sem sobreposição.
Lead score e health score gravados por dia, para medir se a régua acertou sem reescrever o que o time viu.
Atributos por conta e mês calculados no fim do mês anterior, para prever churn e NRR sem vazar o futuro.