Troubleshooting & Solução de Problemas Frequentes

Troubleshooting & Guia de Diagnóstico

Este documento compila os procedimentos de solução para os problemas e erros mais comuns enfrentados no desenvolvimento local, testes e operação do Prime Crown.

---

🔍 1. Desenvolvedor / Ambiente Local

A. Conflito de Portas no Ambiente Local (npm run dev / pages:dev)

• Sintoma: O frontend não consegue realizar chamadas para /api/* ou o Wrangler falha ao iniciar na porta 8788.
• Causa: Processos antigos do Node/Wrangler ficaram orquestrados na porta em segundo plano.
• Solução:

  # Matar processos ocupando as portas 3000 e 8788 no macOS
  kill -9 $(lsof -t -i:3000) 2>/dev/null || true
  kill -9 $(lsof -t -i:8788) 2>/dev/null || true
  
  # Reiniciar em dois terminais separados:
  npm run pages:dev # Terminal 1
  npm run dev       # Terminal 2

---

B. Inconsistência de Schema no Banco Local (Schema Drift)

• Sintoma: O teste npm test falha apontando erro em tests/schema_drift.test.ts.
• Causa: Uma alteração foi feita no arquivo functions/api/db/schema.ts (Drizzle), mas não foi espelhada no db/schema.sql.
• Solução:
  1. Verifique quais tabelas/colunas foram adicionadas em schema.ts.
  2. Adicione as instruções SQL equivalentes no db/schema.sql e crie a migração incremental em db/migrations/NNNN_*.sql.
  3. Re-inicialize o banco de dados local com:

     npm run db:init

---

💬 2. Comunicação Omnichannel & WhatsApp (Evolution API)

A. Mensagens de WhatsApp Não Estão Sendo Entregues

• Sintoma: O status da fila em WhatsAppFailuresPanel.tsx mostra tentativas esgotadas (FAILED).
• Diagnóstico:
  1. Acesse o painel de configurações em ChatSettingsPanel.tsx e clique em Check Connection Health.
  2. Verifique se a instância do WhatsApp está conectada (CONNECTED).
• Solução:
  • Se a instância estiver desconectada ou desconectada pelo WhatsApp Web, solicite ao Administrador o escaneamento do novo QR Code na tela de suporte do Chat.

---

B. Bloqueio ou Spam Warning no Envio de Notificações

• Causa: Envio de muitas mensagens em um curto intervalo sem intervalo humano.
• Solução:
  • O sistema possui o middleware de proteção antiBanPolicy.ts. Certifique-se de que os disparos automáticos passem sempre por esse middleware em vez de chamadas HTTP diretas.

---

⚡ 3. Sincronização e Atualizações Otimistas

A. Toast “Sync Failed” na Interface

• Sintoma: O usuário realiza uma ação (ex: muda data de agendamento), o card se move, mas segundos depois surge um toast de erro.
• Causa: A chamada atômica para o Cloudflare D1 em /api/atomic/* retornou erro HTTP (4xx/5xx) ou falha de rede.
• Solução:
  1. A store do Zustand executou o rollback automático para o estado anterior.
  2. Abra as DevTools do navegador ➔ Aba Network ➔ Verifique a resposta JSON do endpoint atômico que falhou para ler a mensagem exata do Zod Validator ou Drizzle.