diego-analytics.pages.dev

Workflow API-first do Analytics

Documento operacional do painel: APIs são fonte da verdade, o dashboard é apresentação. Toda consulta sob demanda ou via cron deve coletar/validar na fonte viva e atualizar o portal quando houver rotina de deploy.

Projeto canônico: diego-analytics

Regra soberana: nunca inferir métrica crítica pelo HTML do dashboard quando a API/fonte viva existe. Snapshot antigo é evidência secundária, não fonte de decisão.

Consulta API-firstPedidos sob demanda e crons começam na API/fonte viva. O HTML só confirma a publicação depois.

Crons diários em BRTInstagram 10:00 · Meta Ads 10:05 · YouTube 10:10 · Newsletter 10:15 · Consolidado 10:20.

Coleta na origemInstagram usa Graph API + SQLite. Meta Ads usa Graph API paginada. YouTube usa YouTube Analytics/Data API. Newsletter usa Ghost Admin/Content API.

NormalizaçãoAs rotinas convertem métricas cruas em estruturas estáveis para HTML: KPIs, séries, tabelas, campanhas, posts, tráfego, segmentos e funis.

Manifesto e snapshotsCada execução atualiza data/capture-manifest.json, snapshots locais e páginas vivas em skills/instagram-analytics/data/live-pages.

Blindagem anti-perdaErro de API não pode virar zero silencioso. Falha deve abortar antes de sobrescrever/deployar HTML ruim.

DeployPublicação sempre no projeto Cloudflare Pages existente diego-analytics. Não criar novo projeto.

Validação pós-deployConferir rotas 200, timestamp BRT, ausência de login legado e números críticos batendo com a API.

Área	Fonte viva	Script principal	Regra crítica
Instagram	Instagram Graph API + SQLite local	`skills/instagram-analytics/scripts/deploy.sh`	Graph API v22+: usar métricas válidas; não publicar zero falso.
Meta Ads	Meta Marketing/Graph API	`scripts/update-meta-ads-dashboard.sh`	Campanhas com paginação completa; ativa = `effective_status=ACTIVE`.
YouTube	YouTube Analytics API + Data API	`scripts/run-youtube-dashboard-cron.sh`	Renovar token, coletar dados vivos e falhar se API/token quebrar.
Newsletter	Ghost Admin/Content API	`scripts/update-newsletters-dashboard.sh`	Agregados no HTML; sem nomes/emails ou PII versionada.
Google Ads	Sem coletor real ativo	stub	Tratar como placeholder até implementação validada.

Objetivo

Ser o painel único de performance do Diego, útil para decisão rápida e honesto sobre a qualidade/frescor dos dados.

Pedido sob demanda

Consultar API/fonte viva.
Atualizar dashboard se houver rotina.
Responder com timestamp BRT.
Explicar fonte usada e limitações.

Meta Ads

Não usar HTML para contar campanhas ativas.
Não usar recorte limit=20 como universo.
Validar status, effective_status e configured_status.

Qualidade

Erro de API não vira zero.
HTML anterior sobrevive a falha.
Manifesto indica atualizado/parcial/stale/falhou.
Snapshot vivo vence HTML local antigo.

Fora de escopo

Criar outro projeto Cloudflare Pages.
Guardar segredo no repositório.
Tratar Google Ads como ativo sem coletor real.
Reintroduzir login sem nova decisão.

Runbook canônico

Arquivo técnico completo no workspace: docs/analytics-dashboard-api-first-runbook.md.