Troubleshooting & Solução de Problemas Frequentes
Troubleshooting & Guia de Diagnóstico
Section titled “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
Section titled “🔍 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)
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 porta8788. - 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 macOSkill -9 $(lsof -t -i:3000) 2>/dev/null || truekill -9 $(lsof -t -i:8788) 2>/dev/null || true# Reiniciar em dois terminais separados:npm run pages:dev # Terminal 1npm 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 testfalha apontando erro emtests/schema_drift.test.ts. - Causa: Uma alteração foi feita no arquivo
functions/api/db/schema.ts(Drizzle), mas não foi espelhada nodb/schema.sql. - Solução:
- Verifique quais tabelas/colunas foram adicionadas em
schema.ts. - Adicione as instruções SQL equivalentes no
db/schema.sqle crie a migração incremental emdb/migrations/NNNN_*.sql. - Re-inicialize o banco de dados local com:
Terminal window npm run db:init
- Verifique quais tabelas/colunas foram adicionadas em
💬 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.tsxmostra tentativas esgotadas (FAILED) ou mensagens retidas (HELD). - Diagnóstico:
- Em Settings → Messaging, veja o card Delivery Health: número na Meta, webhook, cota mensal e taxa de recibos.
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.
🌐 3. Tradução & Provedores de IA
Section titled “🌐 3. Tradução & Provedores de IA”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:
- O sistema utiliza primeiro o Cloudflare Workers AI (
@cf/meta/llama-3.2-1b-instruct). Verifique se o binding[ai] binding = "AI"está nowrangler.toml. - 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.
- O sistema utiliza primeiro o Cloudflare Workers AI (