Pré-Auditoria Automática de Criativos¶

Sistema que analisa imagens e vídeos via Gemini 2.5 Flash quando uma task entra em status de revisão no ClickUp. Publica o feedback como comentário na task e (opcionalmente) em um canal do ClickUp Chat.

Fluxo¶

Task → status contém "revis" → ClickUp webhook → /webhook/clickup/pre-auditoria
  → getTask()
  → valida: lista mapeada? status de revisão?
  → escolhe modo:
      • "Link da Mídia" preenchido → download Drive → analyzeMedia (Gemini visão)
      • Copywriting sem mídia + "Legenda" → analyzeText (Gemini texto)
  → postComment() na task
  → [opcional] postChannelMessage() no canal
  → audit.log()

Listas que acionam¶

Lista	ID	Modo
Design & Criação	`901325235657`	Visão (imagem)
Gravação & Edição	`901325235661`	Visão (vídeo)
Copywriting	`901325235663`	Visão se tem mídia; texto se só tem Legenda

Hardcoded em AUDIT_LISTS em server/automations/pre-auditoria.js. Para adicionar lista nova: editar este objeto.

Status que dispara¶

Qualquer status cujo nome contenha "revis" (includes('revis') lowercase). Cobre: "Revisão", "Em Revisão Interna", "Revisão Externa", "Revisão IA", etc.

Custom fields lidos¶

Campo ClickUp	Uso
`Link da Mídia` (URL)	Fonte do arquivo. Aceita URL de arquivo OU pasta do Drive (pega o 1º arquivo de mídia)
`Legenda` (Text)	Copy analisada quando não há mídia (só Copywriting)
`Formato de Conteúdo`	Injetado no prompt como contexto
`Persona Alvo`	Injetado no prompt como contexto
`Objetivo do Período`	Injetado no prompt como contexto

Env vars (Easypanel → apiclickup)¶

Var	Descrição	Obrigatório
`ENABLE_PRE_AUDITORIA`	Gate master. `true` para ligar	Sim
`GEMINI_API_KEY`	Google AI Studio	Sim
`CLICKUP_TOKEN`	Token existente (reusa)	Sim
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` / `GOOGLE_REFRESH_TOKEN`	OAuth2 Drive existente (reusa)	Sim
`PRE_AUDITORIA_CHANNEL_ID`	Canal ClickUp Chat para publicar além do comentário	Não
`CLICKUP_WORKSPACE_ID`	Default `9010129117`	Não

Endpoints¶

Método	Path	Uso
POST	`/webhook/clickup/pre-auditoria`	Webhook produtivo (ClickUp chama)
POST	`/pre-auditoria/trigger/:taskId`	Disparo manual para testes
GET	`/pre-auditoria/debug`	Verifica flags/envs carregadas

Webhook ClickUp¶

Evento: taskStatusUpdated
URL: https://gita-apiclickup.ewzc9p.easypanel.host/webhook/clickup/pre-auditoria
Handler tolera webhooks fora do escopo — ignora com log quando lista não está em AUDIT_LISTS ou status não contém "revis".

Arquivos¶

server/
├── gemini.js                       # Cliente Gemini: analyzeMedia + analyzeText + Files API (vídeos >20MB)
├── clickup-chat.js                 # postChannelMessage (API v3 experimental)
├── google-drive.js                 # +downloadFile, +extractDriveFileId, +extractDriveFolderId, +listFolderFiles
└── automations/
    └── pre-auditoria.js            # Handler webhook + trigger manual + debug

Onde ajustar¶

Quero mudar...	Arquivo:linha
Prompt visual (imagem/vídeo)	server/gemini.js — `buildVisualPrompt`
Prompt de texto (copy)	server/gemini.js — `buildTextPrompt`
Modelo Gemini	server/gemini.js — const `MODEL`
Listas que acionam	server/automations/pre-auditoria.js — const `AUDIT_LISTS`
Formato do comentário	server/automations/pre-auditoria.js — `formatComment`
Formato da msg do canal	server/automations/pre-auditoria.js — `channelMsg` inline em `processTask`
Regra de status	server/automations/pre-auditoria.js — `includes('revis')`
Changeset de campos lidos	server/automations/pre-auditoria.js — objeto `context`

Limitações conhecidas¶

Prompt genérico: não injeta brand guidelines específicos da Gita nem do cliente da task. Para melhorar, ler data/brand/ e injetar no prompt.
Sem acesso à pauta original: não compara com briefing anterior. Se um dia a task tiver link para a pauta em campo próprio, puxar e injetar.
Gemini 503: modelo às vezes retorna "high demand". Não há retry — erro vira comentário na task. Considerar retry com fallback para gemini-2.0-flash.
Pasta Drive com múltiplos arquivos: analisa apenas o 1º encontrado. Se precisar analisar todos (carrossel), iterar em listFolderFiles.
Audit log não persiste: server/logs/audit.jsonl é wipado em cada deploy do Easypanel (não é volume). Para histórico duradouro, persistir em Supabase.
API v3 ClickUp Chat: marcada como experimental. Pode quebrar sem aviso.

Verificação rápida¶

# Confirma env vars carregadas
curl https://gita-apiclickup.ewzc9p.easypanel.host/pre-auditoria/debug

# Dispara análise de uma task qualquer em status de revisão
curl -X POST https://gita-apiclickup.ewzc9p.easypanel.host/pre-auditoria/trigger/<TASK_ID>

# Lê últimas execuções (reset a cada deploy)
curl "https://gita-apiclickup.ewzc9p.easypanel.host/audit?event=pre-auditoria&limit=10"

Ideias para evoluir¶

Brand guidelines injection: ler data/brand/{cliente}/guidelines.md dinamicamente e anexar ao prompt
Retry + fallback de modelo: tentar gemini-2.5-flash → gemini-2.0-flash → erro
Persistir audit em Supabase: tabela pre_auditoria_runs com task_id, listName, verdict, duration, raw_output
Detecção de veredicto: parsear ✅ APROVADO / ⚠️ REQUER REVISÃO e atualizar custom field da task
Multi-file: analisar todos arquivos da pasta como carrossel (1 comentário consolidado)
Brand voice comparativo: além de checklist, scorear coerência com brand voice por cliente