Skip to content

Troubleshooting & Solução de Problemas Frequentes

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.


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)

Section titled “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:
    Terminal window
    # 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)

Section titled “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:
      Terminal window
      npm run db:init

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

Section titled “💬 2. Comunicação Omnichannel & WhatsApp (Meta Cloud API)”

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

Section titled “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) ou mensagens retidas (HELD).
  • Diagnóstico:
    1. Em Settings → Messaging, veja o card Delivery Health: número na Meta, webhook, cota mensal e taxa de recibos.
    2. HELD é a janela de 24 h fechada (o cliente precisa escrever, ou um template aprovado); cota atingida retém até o dia 1.
  • Solução:
    • Número desconectado ou com qualidade vermelha se resolve no WhatsApp Manager; token e phone number ID em Settings → Messaging.

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

Section titled “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. Em Settings → In-app intelligence, confira o modelo do recurso e a utilização. Consulte os erros do Worker se o modelo configurado e o de reserva falharem.