ModularReports: Jornadas dos Atores

Documentos da família

• DRS (modularreports), o que o sistema faz.
• Roadmap de Implementação (modularreports-roadmap), em que ordem construir e como verificar.
• Inventário de Artefatos (modularreports-inventario), tudo que precisa existir e como cada item deve ser.
• Plano de Testes (modularreports-testes), o que validar antes de entregar.
• Questionário de Elicitação (modularreports-questionario), decisões de produto em aberto.

Este documento descreve como cada papel opera o ModularReports, função por função, na cadeira do operador. Complementa o DRS (bloco 2, catálogo de atores e capacidades) com o passo a passo real: como a função começa, onde ela acontece, e o que a pessoa faz. Serve treinamento, onboarding e validação (o Plano de Testes usa uma jornada como base de cada item Beta).

Como ler

Cada papel é uma seção; cada função do papel é uma subseção com três perguntas: Como entra (o gatilho, quando a função começa), Onde entra (a tela, o sistema ou o canal) e O que faz (as ações e o resultado). Os papéis são canônicos do ModularHub (nenhum papel novo foi criado para o Reports, RF-ADM-002); os nomes usados aqui são funções, nunca pessoas.

Atores em uma linha

Super Admin

Ligar o módulo Reports para uma agência

• Como entra: uma agência nova (Company) precisa começar a usar o Reports, ou uma agência existente pede o módulo.
• Onde entra: painel do Super Admin, seção de entitlements do Hub.
• O que faz: liga o entitlement reports para a Company; a partir daí a entrada do Reports aparece para os usuários daquela agência sem novo deploy.

Criar a agência e o primeiro admin

• Como entra: uma agência parceira nova assina o uso do ModularReports.
• Onde entra: painel do Super Admin, cadastro de Company.
• O que faz: cria a Company e o primeiro usuário com papel admin; a partir daí o próprio admin gerencia o restante da agência (self-service).

Auditar uso

• Como entra: revisão periódica de uso do módulo, ou investigação pontual.
• Onde entra: painel do Super Admin e log de auditoria (reports.*).
• O que faz: consulta os eventos de publicar, republicar, revogar e encerrar cliente de qualquer agência; acompanha limites e retenção configurados por agência. Para ver os NÚMEROS de audiência de uma agência (o painel de analytics), precisa antes ativar o contexto daquela empresa: em modo global esse painel vem vazio de propósito, porque o acesso ao relatório é por agência e não abre exceção para o papel que enxerga todas.

Marcar um template como Global (e desmarcar)

• Como entra: um template criado dentro de uma agência é bom o bastante para servir de padrão a todas, ou um template Global deixou de servir.
• Onde entra: chrome do Reports, biblioteca de templates, visão do Super Admin (a única que lista também os templates individuais de todas as agências).
• O que faz: marca o template como Global, e a partir daí ele aparece na biblioteca de todas as agências e só o Super Admin o edita, desmarca ou exclui; desmarcar devolve o template à agência que o criou. É gesto exclusivo do Super Admin: nenhum admin de agência promove o próprio template. Uma agência que só quer variar um Global não pede nada aqui, ela duplica o Global para dentro da própria biblioteca.

Ajustar limites, retenção e allowlist de fontes

• Como entra: necessidade de calibrar um limite global (ex.: teto de verbosidade) ou a allowlist de fontes de benchmark/pesquisa de mercado.
• Onde entra: painel do Super Admin, configuração global.
• O que faz: edita os parâmetros de escopo global do bloco 11 do DRS (allowlist, teto de verbosidade); parâmetros de escopo por agência ficam com o admin daquela agência.

Admin de agência

Gerenciar usuários da agência

• Como entra: um operador novo entra na agência, ou alguém sai.
• Onde entra: chrome do Reports, seção Usuários.
• O que faz: cria, edita e desativa usuários da própria agência; não enxerga nem altera usuários de nenhuma outra agência.

Definir a identidade visual da agência e dos clientes

• Como entra: onboarding da agência ou de um cliente novo, ou atualização de marca.
• Onde entra: chrome do Reports, seção Identidade da agência e ficha de cada cliente.
• O que faz: define logo e cor da própria agência (brandiza o chrome e o link público); preenche ou revisa a ficha de identidade visual e o tom de voz de cada cliente; declara a identidade padrão da agência para os casos em que a ficha do cliente está vazia.

Montar e manter templates

• Como entra: a agência tem um tipo de relatório recorrente (fechamento de campanha, comparativo, trimestral, sazonal) que quer padronizar.
• Onde entra: chrome do Reports, biblioteca de templates.
• O que faz: cria, edita, duplica e exclui os templates da própria agência (blocos padrão por tipo); também aprova quando um operador salva um relatório existente como template novo. Todo template que nasce aqui é individual da agência. A biblioteca mostra ainda os templates Globais, que a agência usa e duplica à vontade, mas não edita nem exclui: quem manipula um Global é só o Super Admin. Para variar um Global, o caminho é duplicar e editar a cópia.

Declarar que o negócio de um cliente é sazonal

• Como entra: no cadastro de um cliente novo, ou ao revisar a ficha de um cliente existente cujo negócio tem pico de temporada.
• Onde entra: ficha do cliente, no painel de clientes.
• O que faz: marca o cliente como sazonal e, se quiser, informa o mês de pico. A partir daí, todos os relatórios daquele cliente comparam contra o mesmo período do ano anterior, e não contra o período imediatamente anterior, e a base aparece escrita dentro da frase de cada número comparativo. A escolha não é oferecida relatório a relatório de propósito: escolher a base a cada entrega é como o viés entra sem que ninguém perceba. Mudar a marcação depois não altera nenhum relatório já publicado.

Acompanhar o painel de analytics agregado

• Como entra: rotina de acompanhamento da operação da agência.
• Onde entra: chrome do Reports, seção Analytics.
• O que faz: vê visualizações, último acesso, comentários não lidos e duração de produção dos relatórios da própria agência; não vê dados de nenhuma outra agência.

Decidir e executar o offboarding de um cliente

• Como entra: um cliente encerra o contrato com a agência.
• Onde entra: ficha do cliente, ação de encerrar.
• O que faz: encerra o cliente, revogando todos os links publicados de uma vez e disparando o processo de eliminação (apagar snapshots, anonimizar a origem: comentários, watermark, Contact) conforme a retenção configurada; o log de auditoria não é mutado, suas referências apenas deixam de resolver (RN-007).

Declarar o modelo de venda de um cliente

• Como entra: ao cadastrar um cliente novo, ou quando o negócio do cliente muda de forma (um cliente que só gerava lead passa a vender pela própria página).
• Onde entra: painel de clientes do Reports, ficha do cliente.
• O que faz: escolhe entre Venda Consultiva e Venda Direta, ou deixa em branco. A escolha troca apenas o vocabulário das quatro etapas do funil dos relatórios daquele cliente, e não muda a estrutura, a ordem das etapas nem o conjunto de métricas de resultado. Deixar em branco é opção legítima e faz os relatórios daquele cliente usarem o funil livre. Trocar depois não altera nenhum relatório já publicado.

Importar os parâmetros de negócio de um cliente

• Como entra: no começo do contrato, e sempre que o fee, a margem de contribuição ou o comportamento de recompra do cliente mudam.
• Onde entra: painel de clientes do Reports, mesma tela por onde as metas são importadas.
• O que faz: envia o arquivo com os parâmetros vigentes e a data a partir da qual eles valem. Esses números não vêm da plataforma de anúncios porque são do negócio do cliente, e sem eles boa parte da camada de resultado sai como lacuna declarada em vez de número. Confere que os parâmetros entraram e que nenhum deles apareceu como meta, que é coisa diferente: meta tem realizado para comparar, parâmetro é operando de conta.

Operador

Compor um relatório pelo wizard

• Como entra: chegou a hora de montar o relatório de um cliente (fechamento de campanha, comparativo, trimestral, sazonal).
• Onde entra: chrome do Reports, botão "Novo relatório", que abre o wizard de 4 passos.
• O que faz: escolhe cliente, período, cadência e template (passo 1; a cadência é declarada, não deduzida do período, e é ela que define contra o que este relatório vai comparar); preenche o briefing canônico com KPI principal, intenção, destaques e identidade (passo 2); revisa o que a IA entendeu dos artefatos e a lista explícita "o que não achei" (passo 3); confirma a composição proposta bloco a bloco, cada número com a origem visível, e segue para o compositor (passo 4).

Curar o rascunho no compositor

• Como entra: a composição proposta pelo wizard está pronta para revisão humana.
• Onde entra: compositor, três colunas (artefatos e IA, preview, configuração).
• O que faz: edita o texto dos blocos, reordena, esconde o que não serve; pede para regenerar um bloco específico com uma instrução nova; insere criativos (imagens de anúncio); ajusta cor primária, logo e títulos do cliente dentro dos campos liberados; nunca edita à mão um número com proveniência.

Apresentar o rascunho em reunião

• Como entra: reunião de resultados com o cliente antes de publicar.
• Onde entra: compositor, modo apresentar.
• O que faz: abre a apresentação em tela cheia com o rótulo "rascunho" e sem os pins de comentário; navega pelos blocos; sai do modo apresentar sem ter publicado nada.

Publicar o link

• Como entra: o rascunho está curado e aprovado internamente.
• Onde entra: compositor, modal de publicação.
• O que faz: revisa a URL do link, define senha e expiração se quiser (opcionais), gera e confere o QR code, edita e revisa o card de compartilhamento (og:title, og:description, capa) com o preview de como aparece no WhatsApp, e publica; depois copia o link e o QR para enviar pelo canal que quiser (o sistema não envia automaticamente).

Republicar e revogar

• Como entra: um erro é corrigido no rascunho depois de já ter publicado, ou o cliente pede para tirar o link do ar.
• Onde entra: ficha do relatório publicado.
• O que faz: republica (o mesmo link passa a servir o snapshot novo, sem versionar a página, e fica registrado no histórico de alterações interno); ou revoga (o link passa a responder como revogado com página brandada, cache purgado).

Criar um cliente novo de dentro do Reports

• Como entra: um cliente novo chega enquanto o operador já está no fluxo de compor.
• Onde entra: chrome do Reports, atalho de criar cliente no wizard ou na lista de clientes.
• O que faz: cadastra o cliente (Account do Hub) sem sair do chrome do Reports; segue trabalhando no mesmo lugar.

Seguir adiante quando uma guarda de honestidade barra o relatório

• Como entra: durante a composição ou a curadoria, uma guarda impede um número, uma comparação ou uma seção (janela parcial, métrica que não se soma, histórico insuficiente, frase causal sem evidência, comparativo sem base).
• Onde entra: a própria tela onde o trabalho está acontecendo, nunca só na hora de publicar.
• O que faz: lê a mensagem, que nomeia a saída legal daquele caso (a média diária, o recorte equivalente, o pico com a janela nomeada, quantos períodos faltam); adota a saída legal, ou, quando julga que o caso é exceção, escreve a justificativa obrigatória e segue. A justificativa fica gravada com o nome dele, o relatório e a guarda, e a página publicada mostra que aquele item foi liberado por decisão humana. Guarda estrutural (número sem origem, publicar sem sessão humana) não oferece essa saída, e nesse caso o caminho é corrigir o dado.

Acompanhar e resolver comentários

• Como entra: o cliente comentou algo na página publicada.
• Onde entra: widget de comentário (drawer lateral) e a lista de comentários do relatório.
• O que faz: lê o comentário ancorado no bloco, responde ou age sobre o ponto levantado, e marca como resolvido; isso notifica o autor. Se o bloco comentado sumir numa republicação, o comentário continua visível com a marca "versão anterior".

Programar a geração automática de um relatório recorrente

• Como entra: quando um cliente passa a receber relatório de forma periódica e não mais avulsa.
• Onde entra: tela de agendas do Reports.
• O que faz: cria a agenda para aquele cliente e aquele propósito, declarando a periodicidade, o dia do ciclo em que a edição deve nascer, o modelo a usar e quem é o responsável por revisar. A partir daí a edição nasce sozinha a cada período, já comparada com a anterior. Um cliente e um propósito têm uma agenda só; se precisar de outra periodicidade para outro propósito do mesmo cliente, cria uma segunda agenda para esse outro propósito. Continua podendo montar um relatório avulso desse cliente quando quiser, fora da agenda.

Pausar e retomar uma agenda

• Como entra: quando o cliente entra em pausa contratual, quando a operação para por um período, ou quando é hora de voltar.
• Onde entra: tela de agendas do Reports, na linha da agenda.
• O que faz: pausa a agenda e nada mais acontece: nenhuma edição nova nasce, e a configuração, o histórico e os links já entregues ao cliente continuam todos no lugar. Ao retomar, a próxima edição nasce só no próximo período que vencer; os períodos que passaram durante a pausa aparecem listados como ciclos sem edição, e quem quiser recuperar algum deles monta esse relatório à mão, um de cada vez. Nada nasce em lote no ato de retomar.

Revisar a edição que o sistema gerou sozinho

• Como entra: pelo aviso de que existe uma edição nova aguardando revisão, ou pela lista de rascunhos.
• Onde entra: compositor do Reports.
• O que faz: lê a edição que nasceu do agendamento como leria qualquer rascunho, confere a comparação com a edição anterior, cura o que precisa curar e publica. A publicação continua sendo um gesto dele: nenhuma edição vai ao ar sozinha, e a edição agendada atravessa exatamente as mesmas conferências de origem do número e de honestidade que uma edição montada à mão atravessa. Quando um período vence e a edição não nasce, recebe o aviso com o motivo e decide o que fazer, porque o sistema não tenta de novo por conta própria.

Cliente final

Receber e ler a página de resultados

• Como entra: recebe o link (por WhatsApp, email ou qualquer canal, enviado manualmente pelo operador) ou lê o QR code.
• Onde entra: o link público, sem login.
• O que faz: lê o snapshot do relatório com a identidade visual da própria marca aplicada; se disponível, baixa o PDF; se o link estiver revogado ou expirado, vê uma página brandada da agência pedindo para solicitar um novo link.

Ativar acesso e comentar

• Como entra: quer comentar algo na página e ainda não tem sessão.
• Onde entra: a própria página pública, atalho de pedir acesso.
• O que faz: pede acesso, recebe um magic link do Hub, autentica; a partir daí o campo de comentário fica habilitado e consegue comentar ancorado num bloco específico da página; recebe notificação quando o comentário é resolvido pela agência.

Acompanhar os relatórios pelo portal logado

• Como entra: já tem acesso ativado e quer ver os relatórios num lugar só, sem depender de guardar cada link.
• Onde entra: o portal logado do cliente (opcional), pela sessão do Hub.
• O que faz: vê a lista dos relatórios publicados dos Accounts a que pertence, abre cada um pelo atalho e acompanha os comentários recentes; é só leitura, não compõe, não publica, não administra nada, e não enxerga relatório de cliente a que não pertence.