Pular para conteúdo

Debriefing diário dos grupos de clientes

Implementado em 2026-06-09.

Objetivo

Às 19h de cada dia, cada grupo ativo de cliente recebe um resumo curto do que avançou, do que continua em andamento, do que aguarda retorno e dos próximos passos explicitamente combinados. Grupos sem mensagens na janela são ignorados.

O resumo considera as duas direções da conversa:

  • mensagens dos participantes do grupo;
  • mensagens fromMe enviadas pelo número oficial da Gita, inclusive revisões e entregas disparadas por outras automações.

Arquitetura

  1. A UaZapi entrega mensagens em POST /webhook/whatsapp/grupos-clientes.
  2. O webhook persiste provider_message_id, dedup_key, from_me, track_source e metadados mínimos em mensagens_grupos.
  3. Às 19h, 19h10 e 19h20 BRT, o cron busca os grupos com ativo=true, debriefing_ativo=true e jid preenchido.
  4. Antes de resumir, o job reconcilia as mensagens fromMe recentes com /message/find. Isso cobre indisponibilidade temporária do webhook.
  5. A janela é contínua: 19h do dia anterior até 19h do dia de referência.
  6. Conversas grandes usam síntese hierárquica em blocos. O prompt proíbe inferências, prazos ou entregas que não estejam explícitos na conversa.
  7. claim_grupo_debriefing adquire um lock atômico por grupo e data.
  8. O texto é salvo antes do envio. Em retry, o histórico da UaZapi é consultado para reconhecer uma mensagem aceita mesmo se a primeira requisição expirou.

Banco de dados

Aplicar antes do deploy:

server/migrations/007-grupos-debriefing-diario.sql

A migration:

  • habilita o debriefing por padrão para grupos atuais e futuros;
  • desabilita o grupo interno com slug gita;
  • adiciona direção, IDs de provider e deduplicação às mensagens;
  • corrige o retry da curadoria e remove reentregas legadas idênticas;
  • cria debriefings_grupos_diarios;
  • cria o RPC idempotente claim_grupo_debriefing.

Para pausar um cliente sem apagar o grupo:

update grupos_clientes
set debriefing_ativo = false
where slug = 'slug-do-cliente';

Configuração

ENABLE_GRUPOS_DEBRIEFING=true
GRUPOS_DEBRIEFING_MODEL=claude-haiku-4-5-20251001
UAZAPI_TOKEN_GRUPOS=...
GRUPOS_WEBHOOK_SECRET=...

Gere o segredo com openssl rand -hex 32, configure a mesma URL na UaZapi e não registre o valor em documentação ou logs:

node server/setup-webhook-uazapi.js

O cron usa também ANTHROPIC_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_KEY e DASHBOARD_TOKEN.

Operação segura

Gerar preview de um grupo, sem criar execução e sem enviar:

curl -X POST \
  "https://gita-apiclickup.ewzc9p.easypanel.host/grupos-clientes/debriefing/preview?token=$DASHBOARD_TOKEN&grupo=debora&data=2026-06-09"

Executar manualmente um grupo:

curl -X POST \
  "https://gita-apiclickup.ewzc9p.easypanel.host/grupos-clientes/debriefing/run?token=$DASHBOARD_TOKEN&grupo=debora&data=2026-06-09"

Consultar o resultado:

curl \
  "https://gita-apiclickup.ewzc9p.easypanel.host/grupos-clientes/debriefing/status?token=$DASHBOARD_TOKEN&data=2026-06-09"

force=true reabre uma execução já concluída. Use somente após confirmar que a mensagem anterior deve ser substituída; o histórico exato ainda evita o reenvio do mesmo texto.

Estados e retries

Status Significado
processing worker possui o lock
sent mensagem confirmada na UaZapi
skipped_no_messages nenhuma mensagem útil na janela
failed falha registrada em last_error

Falhas podem ser retomadas após cinco minutos, até três tentativas. Processos travados podem ser retomados após quinze minutos. As execuções de 19h10 e 19h20 servem de retry; a constraint (grupo_id, data_referencia) impede duplicatas.

Testes

cd server
npm test

Os testes cobrem normalização de payload, captura fromMe, deduplicação, autenticação do webhook, janela 19h–19h, síntese em blocos, filtro de grupos vazios, reconciliação UaZapi e idempotência do envio.