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

graph TD
    Problem["Erro ao iniciar a aplicação local"] --> PortCheck{"Conflito de Porta (3000 / 8788)?"}
    PortCheck -->|Sim| KillPort["Executar: kill -9 $(lsof -t -i:3000 -i:8788)"]
    PortCheck -->|Não| DBCheck{"Erro de Banco D1 SQLite?"}
    DBCheck -->|Sim| InitDB["Executar: npm run db:init"]
    DBCheck -->|Não| TypeCheck["Executar: npm run check"]

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 na aba Failures de ChatOpsPanel.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. Tradução & Provedores de IA

A. Falha na Tradução de Mensagens no Chat

• Sintoma: A mensagem exibe o texto original e o botão de tradução falha silenciosamente.
• Solução:
  1. O sistema utiliza primeiro o Cloudflare Workers AI (@cf/meta/llama-3.2-1b-instruct). Verifique se o binding [ai] binding = "AI" está no wrangler.toml.
  2. Se o Workers AI falhar, certifique-se de que a variável GEMINI_API_KEY esteja configurada no Cloudflare Secrets para acionar o fallback do Gemini.