ClickUp

Existem dois motores distintos e isolados, e a confusão entre eles é o erro mais comum de quem chega.

Motor	Direção	Quando	Estado
Sincronização	Mão dupla, contínua	Sempre	A descontinuar
Importação	ClickUp para KP, mão única	Sob demanda, no onboarding	Em produção

Não unificar os dois

A importação tem namespace, cliente HTTP e tabelas próprios. Ela não usa ClickUpSyncService, nem ClickUpClient, nem as tabelas clickup_*. Compartilha apenas o token lido da configuração. A duplicação de código HTTP é aceita de propósito: o sync será descontinuado e precisa poder ser removido sem afetar a importação. Ver AD-007.

Sincronização

Existe um único motor de sincronização. Áreas novas se integram a ele por adaptador de área, nunca por um segundo motor paralelo. Ver AD-001.

Peça	Tabela
Configuração	clickup_settings
Vínculo de tarefa	clickup_task_links
Vínculo de lista	clickup_list_links
Mapeamento de campo	clickup_field_mappings
Conflito por campo	clickup_conflicts
Log	clickup_sync_logs

Merge de três vias

A sincronização compara o que está aqui, o que está lá e o último snapshot conhecido. É isso que permite detectar conflito por campo em vez de sobrescrever um lado inteiro.

Todo campo sincronizado é string

Tipos ricos, como rótulos múltiplos, dropdown, moeda e data, são codificados e decodificados nas bordas por um CustomFieldCodec. A representação canônica ser string é o que preserva o merge de três vias, o snapshot e o conflito por campo. Ver AD-002.

Webhook

O webhook do ClickUp é autenticado por HMAC.

Configuração

O token fica no .env. As telas de configuração estão em Configurações, na seção de integrações.

Importação

Serve ao onboarding de um cliente que já opera no ClickUp e quer trazer a base.

A sincronização não serve para isso: ela é amarrada a uma lista por área e a um board único, importa tudo ou nada, não deixa escolher a origem e não acomoda uma operação que não seja funil de vendas.

flowchart LR
  A[Escolher espaço e lista] --> B[Revisar o que veio]
  B --> C[Escolher lead a lead]
  C --> D[Indicar o pipeline de destino]
  D --> E[Confirmar]

Garantia	Como
Ver antes de confirmar	A revisão acontece antes da gravação
Reimportar não duplica	Vínculo em lead_import_links
Rastro de cada execução	lead_import_runs
Destino explícito	O operador indica para qual pipeline vai

A taxonomia é espelhada, não inventada

Etapas, origens, faixas de faturamento, produtos e motivos de desqualificação vêm do ClickUp e vivem em tabelas seedadas, servidas ao cliente por endpoint de metadados. Nunca lista fixa no frontend. Ver AD-003.

Importação de planilha

Fora do ClickUp, duas importações de planilha já rodaram e valem como referência do que existe hoje:

Planilha	O que trouxe	Regra
Controle de entregas	1243 entregas	Nenhuma virou compromisso na agenda (AD-014)
Datas para Eliezer	134 linhas com tutor, hora e duração	Viraram compromisso, e o especialista é registro (AD-019)

A diferença entre as duas é exatamente a presença de tutor, hora e duração.