# Dados e indicadores confiáveis

Um número só é útil quando você sabe o que ele significa.

Contratos para métricas, estados de disponibilidade e coleta consentida. Uma base de engenharia para que interfaces e aplicações de IA não tratem informação ausente como fato medido.

Data contracts · React · Express · PostgreSQL · Consent · Testing

Componentes de dados · testes locais

## O problema por trás de um indicador aparentemente simples

Um dashboard pode mostrar zero porque nenhuma ocorrência foi registrada, porque o filtro não encontrou dados ou porque uma integração não respondeu. Esses estados têm implicações diferentes para uma decisão de negócio. Eu conduzi a implementação e a validação de contratos que preservam essas diferenças, junto a controles de privacidade na coleta. O objetivo foi tornar a informação interpretável antes de utilizá-la em uma interface ou assistência por IA.

Um gráfico visualmente convincente não corrige um contrato ambíguo. A engenharia começa pela definição do indicador, pela origem disponível e pelas condições em que a aplicação pode apresentar um valor.

## Como este caso se conecta ao produto

O trabalho reúne componentes de analytics e coleta. React e Vite sustentam uma fonte de interface, enquanto Express e PostgreSQL aparecem na arquitetura de backend. O briefing descreve contratos de payload, classificação de filtros, disponibilidade de métricas, consentimento e minimização de dados. As evidências são testes locais do recorte, sem conexão a contas reais de publicidade ou operações privadas.

A demonstração navegável do CRM permite observar uma experiência de indicadores com dados sintéticos. Ela não é apresentada como certificação das integrações deste caso. Separar experiência visual e evidência de integração evita que uma tela seja usada para provar algo que seu ambiente não executa.

## Contratos antes da visualização

Os contratos de payload estabelecem a forma esperada da informação que chega à aplicação. Essa fronteira permite detectar uma estrutura incompatível antes que um componente a converta em um gráfico ou resumo. Classificação de filtros ajuda a manter explícito o recorte que produziu o indicador. Um número isolado da sua definição e do seu período pode ser tecnicamente válido e ainda assim induzir uma interpretação incorreta.

Eu tratei o contrato como parte do produto, não apenas como uma convenção entre programadores. Interface e backend precisam concordar sobre significado, disponibilidade e contexto para que uma decisão assistida tenha uma base compreensível.

## Disponibilidade é informação

Quando a métrica não está disponível, a aplicação deve preservar esse estado em vez de preencher o campo com um zero conveniente. Um zero medido informa algo sobre a operação; indisponibilidade informa algo sobre a capacidade de observá-la. Misturar os dois pode fazer uma pessoa ou um modelo concluir que não houve atividade quando, na verdade, faltou uma leitura confiável.

Essa distinção orienta o comportamento de gráficos, resumos e exportações. Também ajuda a tratar falhas de integração sem camuflá-las como um resultado comercial. A ausência passa a ter significado explícito e pode ser investigada como uma condição operacional.

## Coleta consentida e minimização

O collector exige consentimento explícito no recorte implementado. O tratamento de IP utiliza hash como parte da minimização, reduzindo a exposição do valor bruto no fluxo analisado. Hashing não elimina por si só todas as obrigações de privacidade, e não o apresento como anonimização absoluta. Seu efeito precisa ser entendido dentro do contrato, da finalidade e dos dados que permanecem associados ao evento.

Os testes verificam comportamento de coleta e privacidade com exemplos sintéticos. Nos materiais públicos, não há eventos reais de visitantes, identificadores de campanhas privadas ou dados de terceiros. A mesma disciplina se aplica aos exemplos técnicos usados para explicar o produto.

## Por que isso também é engenharia de IA

Um modelo pode gerar uma explicação fluente a partir de um indicador incorreto ou indisponível. Por isso, melhorar a qualidade da entrada é uma parte importante da integração de IA. A aplicação precisa representar quando existe dado medido, quando há um recorte vazio e quando falta uma dependência. O modelo não deve receber uma ausência silenciosamente convertida em fato numérico.

Esse caso complementa o runtime de agentes e o assistente: contratos e estados de disponibilidade reduzem ambiguidade antes da interpretação. Não equivale a treinamento de modelos, processamento distribuído ou um pipeline de Big Data. É engenharia de dados aplicada à confiabilidade de um produto.

## Escolhas e seus custos

Preferi preservar a indisponibilidade a manter todos os cards preenchidos. Ganhei precisão de interpretação, com o custo de desenhar estados adicionais e explicar seu significado. Preferi consentimento explícito a coleta por conveniência, aceitando que algumas situações não produzam evento. Preferi contratos verificáveis a depender de um formato presumido de resposta externa.

Essas escolhas exigem coordenação entre API, interface e testes. O benefício é permitir que um problema de observação continue visível como tal. A aparência do dashboard não deve pressionar o backend a inventar um valor para completar a composição.

## O que foi exercitado

A auditoria de 4 de outubro de 2026 aprovou 9 testes de contratos, métricas e privacidade, além de 3 testes do collector. Os 12 testes focais verificam regras locais nas fontes analisadas. Não houve uso de integração de publicidade real ou dado privado para comprovar os cenários. A validação sustenta os comportamentos exercitados, sem transformar esse recorte em uma certificação integral de analytics.

Não declaro resultados financeiros, processamento em escala distribuída ou treinamento estatístico com base nessas evidências. A contribuição verificável é o desenho e a implementação de fronteiras que impedem confundir ausência de informação, formato incompatível e um valor legitimamente medido.

## O próximo passo depende da pergunta

Uma evolução começaria pela decisão que o indicador precisa apoiar. Depois, seriam definidos origem, período, critérios de disponibilidade e casos de falha. Integrações reais exigiriam contratos certificados em ambiente adequado, com dados sintéticos sempre que possível. Só então faria sentido avaliar alertas, comparações ou narrativas produzidas por modelos sobre essas métricas.

Esse roteiro é uma proposta de evolução, não uma etapa já executada. O caso mostra que construir um produto com IA também significa cuidar da informação que chega ao modelo: sua definição, seus limites, sua qualidade e sua relação com o que a interface permite concluir.

---
César Machado · https://cesarmachado.com