Relatórios, digest e métricas

Objetivo

A Radhr AI não tem "dashboard". A leitura gerencial chega em quatro formatos, todos montados a partir dos mesmos dados da Home Hoje e dos eventos: o Digest (e-mail diário de cada Consultor com a sua fila), o Relatório semanal (a semana em números, a carteira, o Health Score, a documentação viva e uma narrativa curta), as Métricas de funil (onde a Radhr AI ganha e perde) e o briefing narrado no topo da Home. Em todos, os números são do código; a IA só escreve sobre eles, com o perfil da organização como contexto. O custo de IA aparece nas métricas, no relatório e na página da organização.

Fluxo

Nos dias úteis às 8h (Brasília), o cron diário roda por organização ativa, cada uma no seu contexto: aviso de fim de teste, Motor de risco dos clientes, escalações de etapas atrasadas, Health Score, Delivery Advisor, auditoria por conversas e, por último, o Digest. Um passo que falha é logado e não impede os seguintes; uma organização que falha não para as outras.
Para cada usuário da organização, o Digest monta a Home dele (os leads e clientes dele e os sem dono) e envia o e-mail, a menos que o dia esteja vazio. No mesmo passo grava uma linha de Score por lead aberto em lead_scores.
O resultado do envio (quem recebeu, quem ficou sem e-mail, falhas) fica no evento digest_enviado.
Toda segunda às 8h30, o cron semanal roda o Organization Auditor, o Customer Success, a Expansão da carteira e depois o Relatório semanal: números da semana que acabou contra a anterior, pipeline, quem se moveu, riscos, Health Score, Documentação viva e carteira; a IA escreve a narrativa e o e-mail sai para os admins da organização (os sócios) com e-mail. Evento relatorio_semanal_enviado e, na Witbiz, docs_saude_semanal com o score da documentação.
Se a Cloudflare não disparar o diário ou o semanal, o cron horário percebe depois das 12h UTC (9h de Brasília) e roda o que faltou, com o evento cron_recuperado na Witbiz. O master também pode rodar qualquer cron na hora em /radar/plataforma ("Rodar agora").
A qualquer hora, o Consultor abre /radar/relatorio (prévia montada e narrada na hora, com botão de enviar agora para admin), /radar/digest (a prévia do seu e-mail) ou /radar/metricas (funil do período).
Ao abrir a Home, a Radhr AI monta a fila e pede à IA um briefing de duas a três frases; se já existe um para os mesmos dados, reaproveita.

Regras de negócio

Parceiros no relatório (ADR-0014, sprint 3): só na Witbiz, o relatório semanal traz o bloco "Parceiros" — parceiros ativos, pendentes de aprovação e em análise, clientes pagantes de vinculados, MRR via parceiros da última competência, comissões e a pagar dos fechamentos — com link para o painel do programa.

Um lugar para os crons: o disparo da Cloudflare (scheduled() em src/index.ts) e o "Rodar agora" chamam a mesma executarCron, que roda por organização ativa e grava no KV o marcador do último disparo. Horários em UTC no wrangler.jsonc: 0 11 * * MON-FRI (diário) e 30 11 * * MON (semanal). Vive em src/cron.ts (executarCron, CRONS).
Recuperação do cron perdido: a partir das 12h UTC, o cron horário compara o marcador com o dia: diário em dia útil ou semanal na segunda com marcador de outro dia roda agora, para todas as organizações, com evento cron_recuperado. Sem marcador (deploy novo) não há recuperação. Vive em src/cron.ts (cronsAtrasados, recuperarCrons).

Digest só com novidade: se a Home do usuário não tem ações, riscos nem chegadas, o e-mail não sai. Mostra até 3 ações, os riscos, até 5 chegadas das últimas 24 h e as oportunidades. Vive em src/digest.ts (rodarDigest, htmlDigest).
Digest é pessoal: cada usuário recebe só o que é dele e o que ainda não tem dono. Vive em src/digest.ts e src/hoje.ts (montarHoje).
Snapshot diário de Score: o Digest grava probabilidade, temperatura e valor potencial de cada lead aberto em lead_scores, o histórico para calibrar o Score. Vive em src/digest.ts (gravarSnapshotScores).
Destinatário do e-mail: o e-mail cadastrado do usuário. Sem ele, só na Witbiz (organização 1) o código usa os segredos EMAIL_ALBERTO/EMAIL_CAROLINA pelo login e, por último, EMAIL_ALBERTO. Em outra organização, o usuário sem e-mail não recebe; o digest dele nunca vai para a Witbiz. Vive em src/db.ts (emailDoConsultor).
Semana do relatório: rodando na segunda antes do meio-dia, é a semana que terminou (segunda a domingo, horário de Brasília); em outro dia, a semana corrente. Vive em src/relatorio.ts (montarRelatorio).
Números da semana: leads novos, handoffs, reuniões registradas, propostas enviadas, aberturas de pré-proposta e de proposta, ganhos, perdidos e custo de IA, cada um contra a semana anterior. Vive em src/relatorio.ts (contar).
Custo de IA no relatório soma o custo_usd gravado nos eventos dos leads (resumos, análises, próxima ação); não é o total da organização. O total está em /radar/organizacao e em /radar/metricas. Vive em src/relatorio.ts.
Carteira no relatório: clientes ativos (todos fora de churn), em risco, renovando, contratado, contratos assinados que terminam em até 60 dias, até 2 sugestões de expansão por cliente, valor das oportunidades de upsell e renovação abertas e margem média das propostas aceitas. Vive em src/relatorio.ts.
Narrativa da IA: três parágrafos curtos, SEMANA, TRAVADO e FOCO, até 120 palavras, só com os números e nomes fornecidos. Sem resposta, o e-mail sai com "Narrativa indisponível nesta semana". Vive em src/relatorio.ts (narrar).
Narrativa com cache: guardada em analises_ia com hash da entrada e do perfil da organização; a prévia e o envio de segunda com os mesmos números não chamam o modelo de novo. "Enviar agora" manda o e-mail aos mesmos destinatários do cron (os admins). Vive em src/relatorio.ts (narrar) e src/radar/paineis.ts.
Perfil da organização na IA: briefing e narrativa usam o nome e o perfil publicado da organização (não mais "da Witbiz" fixo); mudar o perfil muda o hash e gera texto novo. Vive em src/briefing.ts, src/relatorio.ts e src/perfil/contexto.ts (contextoOrganizacional).
Health Score no relatório: a última medição e o delta contra a de 7 dias atrás, com a primeira recomendação. Vive em src/relatorio.ts (tendenciaSaudeSemanal).
Documentação viva no relatório: seção do e-mail de segunda e da prévia, montada pelo código:
Só na Witbiz (organização 1): Living Documentation Score contra a meta 90, delta contra a semana anterior, risco e quantos documentos estão desatualizados. O score da semana é gravado no evento docs_saude_semanal só no envio de segunda (cron ou "Enviar agora"), nunca na prévia; o delta compara com o último desses eventos.
Em todas as organizações: perguntas à documentação na semana contra a anterior (assistente e Copiloto, tabela doc_perguntas), quantas ficaram sem fonte, a taxa de respostas avaliadas como úteis e até 3 perguntas sem resposta.
Pendências abertas na fila de revisão e as áreas funcionais que pedem treinamento (mudança de tela, ação, agente, ferramenta ou cadeia no changelog da semana, ou documento revisado), com link para /radar/conhecimento/treinamento.
A seção some quando não há nada a dizer; se a base não puder ser lida, o relatório sai sem ela. Vive em src/relatorio.ts (documentacaoDoRelatorio, htmlDocumentacao) e src/conhecimento/saude.ts (saudeDaDocumentacao).
Métricas de funil: coorte = leads criados no período (30, 90 ou 365 dias; padrão 90). Etapas: leads criados, qualificados, pré-proposta gerada, pré-proposta aberta, handoff, reunião agendada, proposta enviada, ganho, com a conversão sobre a etapa anterior. Também: triagem (conversas, com fala do visitante, identificadas), perdidos, tempos medianos entre etapas, cortes por Momento e por Origem. Tudo derivado dos eventos, sem tabela própria. Cada organização vê as suas; o master (admin da Witbiz, fora de impersonação) vê as de outra com ?org=<id>. Vive em src/metricas.ts (calcularMetricas) e src/radar/paineis.ts.
Estágio atual conta como alcançado: um lead criado à mão já em handoff entra no funil até o handoff, mesmo sem evento. Vive em src/metricas.ts.
IA nas métricas: custo total e por rótulo do período (tabela ia_chamadas), custo por lead qualificado e o desfecho das Próximas ações (executada, editada, dispensada). Vive em src/metricas.ts.
Briefing da Home: só quando há ações ou riscos; um parágrafo de até 320 caracteres, sem números novos, citando empresas pelo nome. Guardado em analises_ia (tipo briefing, por usuário) com hash dos dados: mesmo dia e mesma fila não chamam o modelo de novo. Falhou, a Home usa a frase determinística. Vive em src/briefing.ts (narrarBriefing).
Custo de IA por organização: cada chamada ao modelo grava tokens e custo em ia_chamadas; a página /radar/organizacao soma o mês por rótulo e compara com o limite do plano. O resumo do lead e a narrativa do relatório semanal também entram (desde 25/09/2026). Vive em src/claude.ts (registrarChamadaIA) e src/organizacao.ts (usoIaDoMes).

Casos de uso

Começar o dia sem abrir a Radhr AI. O Digest das 8h diz o que fazer primeiro, quem está em risco e quem chegou; cada item tem link direto.
Conferir por que alguém não recebeu o digest. Veja o evento digest_enviado: ele lista, por usuário, ações, riscos, chegadas, se foi enviado e o erro (por exemplo, "sem e-mail").
Reunião de sócios na segunda. Abra /radar/relatorio para a versão atualizada e use FOCO como pauta.
Saber se a documentação está acompanhando o código. Na seção Documentação viva, score abaixo de 90 ou documentos desatualizados pedem revisão; perguntas sem resposta mostram o que falta escrever; áreas que pedem treinamento viram roteiro em /radar/conhecimento/treinamento.
O digest das 8h não chegou. Depois das 9h o cron horário roda o diário que faltou; se precisar antes, o master usa "Rodar agora" em /radar/plataforma.
Entender onde o funil vaza. Em /radar/metricas?dias=90, compare a conversão entre etapas e os tempos medianos; recorte por Origem para ver qual canal traz lead que fecha.
Acompanhar o gasto de IA. /radar/organizacao mostra o uso do mês por rótulo e a barra contra o limite; /radar/metricas mostra o custo por lead qualificado.

Telas

/radar/ (Home): briefing narrado no topo, fila de prioridades e números-filtro.
/radar/digest: prévia do e-mail das 8h do usuário logado, com a contagem de ações, riscos e chegadas.
/radar/relatorio: prévia do Relatório semanal, com Health Score e Documentação viva (narrativa com cache: reabrir com os mesmos números não chama o modelo); para admin, botão "Enviar" que dispara o e-mail agora (POST /radar/relatorio/enviar).
/radar/metricas: funil, tempos, cortes por Momento e Origem e bloco de IA; período por ?dias=30, 90 ou 365; para o master, ?org=<id> com aviso de que é a visão de outra organização.
/radar/conhecimento/uso: uso da documentação da organização (perguntas, pessoas, sem fonte, úteis, busca × Copiloto, por semana, lacunas, documentos mais citados; na Witbiz, o score contra a meta) em 7, 28, 56 ou 90 dias.
/radar/conhecimento/treinamento: módulos por área gerados do changelog (7, 30 ou 90 dias) e roteiro de treinamento escrito pela IA a partir do documento oficial (por regra se a IA falhar).
/radar/plataforma (master): cartão "Crons" com o último disparo de cada um e "Rodar agora".
/radar/organizacao: cartão "Uso de IA neste mês" com total, limite, barra e custo por rótulo.
Copiloto: a ferramenta metricas responde perguntas sobre o funil e o custo de IA em conversa.

Permissões

admin e consultor: acessam todas as telas deste documento. As métricas e o relatório mostram a organização inteira; o digest e a Home mostram o que é do usuário e o que não tem dono.
Relatório semanal: vai só aos admins (sócios) da organização. O papel vem do vínculo de membro; sem vínculo, do cadastro. Se os papéis não puderem ser lidos, o relatório não sai para ninguém (falha fechada); só antes das migrações 0010 (sem a coluna papel, todos eram admin) e 0019 (sem vínculos) vale o comportamento antigo. "Enviar agora" é só de admin: para os demais, o botão não aparece e o POST volta com aviso. — src/relatorio.ts (destinatariosDoRelatorio), src/radar/paineis.ts
financeiro e leitura: veem as métricas e a prévia do relatório, e recebem o digest e o relatório se tiverem e-mail e forem admins. "Enviar agora" é recusado com 403 (src/radar/permissoes.ts).
Documentação viva: o score e os documentos desatualizados só aparecem para a Witbiz; cada organização vê só as próprias perguntas. Em /radar/conhecimento/treinamento, todos os papéis geram o roteiro, como uma pergunta à documentação (docs.ler); o custo entra no limite de IA da organização.
Crons e métricas de outra organização: "Rodar agora" e ?org= são só do master.
cliente: não recebe nenhum destes relatórios.
Gating de plano: digest diário e relatório semanal estão em todos os planos (src/planos.ts, "incluído em todos"). Com o limite de IA atingido, briefing e narrativa deixam de ser escritos pela IA e os números continuam.

Perguntas frequentes

Não recebi o digest hoje. Quebrou? Provavelmente não: dia sem ações, riscos nem chegadas não gera e-mail. Confira em /radar/digest; se a prévia tem itens, veja o evento digest_enviado e se o seu usuário tem e-mail cadastrado.

Quem recebe o relatório semanal? Os admins da organização (os sócios) que têm e-mail. Os consultores recebem o digest diário, não o relatório.

O custo de IA do relatório bate com o da página da organização? Não precisa bater. O relatório soma só o custo registrado nos eventos dos leads; a página da organização soma as chamadas do mês em ia_chamadas, que é o número que conta para o limite.

Por que o funil mostra um lead como "qualificado" sem evento de qualificação? O estágio atual conta como alcançado: se o lead está em handoff, ele passou por todas as etapas anteriores para o funil, mesmo criado à mão.

O briefing da Home inventa números? Não deveria: o prompt proíbe e recebe só nomes, títulos, urgências e valores da fila. Se a IA falhar, a Home mostra uma frase montada pelo código.

A narrativa do relatório pode estar errada? Ela só pode citar números e nomes enviados pelo código, mas é texto de modelo: confira contra a tabela logo abaixo, que é a fonte.

Por que a seção Documentação viva não apareceu no relatório? Ela some quando não há nada a dizer: fora da Witbiz, sem perguntas nas duas semanas, sem pendências na fila de revisão e sem área pedindo treinamento. Também some se a base de conhecimento não puder ser lida.

Abrir a prévia mexe no delta do score da documentação? Não. Só o envio de segunda (pelo cron ou por "Enviar agora") grava o evento docs_saude_semanal, que é a referência do delta da semana seguinte.

"Rodar agora" o diário manda o digest de novo? Sim: roda o cron inteiro para todas as organizações, como se a Cloudflare o tivesse disparado, sem trava de "já enviado hoje". Use quando o diário não rodou.