Galdix CRM Docs

Tema

Contingência — Quando Integrações Falham ​

O que acontece e o que fazer quando cada integração externa fica indisponível.

Clerk (autenticação) ​

Impacto: Nenhum usuário consegue fazer login. Usuários com sessão ativa continuam até o JWT expirar (~1h).

Sintoma: POST /webhooks/clerk retorna erro, ClerkAuthGuard falha ao verificar tokens.

Ação:

  1. Verificar status em status.clerk.com
  2. Verificar CLERK_SECRET_KEY no Azure Key Vault (pode ter expirado)
  3. Se a chave expirou: gerar nova no Clerk Dashboard → atualizar no Key Vault → bash deploy.sh backend

Degradação aceitável: Enquanto o Clerk estiver fora do ar, nenhuma nova sessão funciona. Operações automatizadas (crons, sync ERP) continuam funcionando pois usam InternalApiKeyGuard.

Meta WhatsApp Cloud API ​

Impacto: Envio de campanhas WhatsApp falha. Mensagens entram na fila mas não saem.

Sintoma: Jobs whatsapp-send falhando com erro 5xx ou timeout da Meta API.

Ação:

  1. Verificar developers.facebook.com/status
  2. Verificar se o accessToken não expirou (StoreWhatsappNumber.accessToken)
  3. Verificar se o número não foi suspenso pela Meta (qualityScore = RED)
  4. Jobs com falha ficam na fila — tentar retry após restauração: POST /admin/queue/retry-failed

Degradação aceitável: Campanhas agendadas ficam pendentes. O sistema tenta reenvio automaticamente via retry do BullMQ.

Chatwoot ​

Impacto: Atendimento ao cliente não funciona. Mensagens recebidas não são roteadas para atendentes.

Sintoma: Webhooks do Chatwoot param de chegar. ChatwootApiService retorna erros.

Ação:

  1. Verificar se o servidor Chatwoot está rodando
  2. Verificar ChatwootConfig.instanceUrl e apiKey
  3. Mensagens recebidas ficam em FailedWebhook para retry

Degradação aceitável: Clientes podem enviar mensagens mas não recebem resposta. Campanhas de WhatsApp continuam funcionando se usam WABA direto.

Evolution API ​

Impacto: Lojas com número Evolution não conseguem enviar/receber mensagens.

Sintoma: Envios via Evolution falham, webhook do Evolution para de chegar.

Ação:

  1. Verificar se o servidor Evolution está rodando
  2. Verificar se o número ainda está conectado (pode precisar de novo QR code)
  3. Acessar o painel Evolution → verificar status da instância

Degradação aceitável: Lojas WABA continuam funcionando normalmente. Apenas lojas Evolution são afetadas.

Millennium ERP ​

Impacto: Dados de clientes, vendas e produtos ficam desatualizados. Nenhuma perda de funcionalidade existente.

Sintoma: POST /erp/sync/trigger falha ou retorna zero registros.

Ação:

  1. Verificar conectividade com MILLENNIUM_BASE_URL
  2. Verificar credenciais (MILLENNIUM_USERNAME, MILLENNIUM_PASSWORD)
  3. Sync manual quando o Millennium voltar: POST /erp/sync/trigger { "startDate": "...", "endDate": "..." }

Degradação aceitável: Sistema continua funcionando com dados do último sync. Campanhas usam dados existentes. Não afeta atendimento.

Redis ​

Impacto: Sistema crítico. Filas BullMQ param de funcionar. Rate limiting falha aberto.

Sintoma: Backend loga erros de conexão Redis. Jobs param de processar.

Ação:

bash
# Verificar status
docker logs crm-galdix-redis-1 --tail 20
docker ps | grep redis

# Reiniciar Redis
bash deploy.sh --restart

Nota: Jobs em voo no momento da queda do Redis serão reprocessados quando Redis voltar (BullMQ com AOF garantido).

PostgreSQL ​

Impacto: Sistema completamente fora do ar. Nenhuma funcionalidade disponível.

Sintoma: Backend falha no health check. Qualquer operação retorna 500.

Ação:

bash
# Verificar status
docker logs crm-galdix-postgres-1 --tail 20
docker ps | grep postgres

# Verificar disco (causa comum)
df -h

# Reiniciar
bash deploy.sh --restart

Azure Key Vault ​

Impacto: Backend não consegue buscar secrets na inicialização. Novo deploy falha.

Sintoma: bash deploy.sh falha ao buscar CLERK_PUBLISHABLE_KEY. Backend falha ao iniciar sem DATABASE_URL.

Ação:

  1. Verificar AZURE_CLIENT_SECRET em /home/crm/.crm-secrets
  2. Verificar se o Service Principal ainda tem acesso ao Key Vault no Portal Azure
  3. Se expirou: renovar o client secret no Portal → atualizar em .crm-secrets

Degradação aceitável: Sistema já rodando continua funcionando (secrets já carregados). Apenas novos deploys e restarts com boot fresh falharão.

MinIO ​

Impacto: Upload de imagens em emails falha. Templates de email sem imagens existentes continuam funcionando.

Sintoma: PUT /uploads/image retorna erro.

Ação:

  1. Verificar servidor MinIO
  2. Verificar credenciais MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_ENDPOINT

Degradação aceitável: Campanhas de email sem novas imagens funcionam normalmente.

Documentação interna — Galdix CRM