Troubleshooting

Guia de diagnóstico para erros comuns na plataforma OLP

---

1. Tabela de Erros Comuns

HTTP	Mensagem	Causa Provável	Solução
400	"Ação não reconhecida"	Frontend chama action inexistente	Verificar nome da action no backend
401	"Não autenticado"	Cookie não enviado ou JWT expirado	Verificar credentials: 'include' e CORS
403	"Acesso negado"	Papel insuficiente	Verificar array de papéis permitidos na EF
429	"Muitas solicitações"	Rate-limit atingido	Aguardar janela (15min sistema, progressivo portal)
500	"Erro interno"	Bug na Edge Function	Verificar logs da EF no Supabase
—	CORS error	Origin não permitida	Adicionar em ALLOWED_ORIGINS do cors-helpers.ts

---

2. Fluxo de Debug

1. Console do navegador (F12)
   └─ Erros JS, stack traces
   
2. Network tab (F12 → Network)
   └─ Status HTTP, body da resposta, headers
   
3. Edge Function logs (Supabase Dashboard)
   └─ console.log/console.error da função
   
4. Banco de dados (logs_transacoes)
   └─ Ações registradas, detalhes JSONB

Links Diretos (Supabase Dashboard)

• Edge Function Logs: https://supabase.com/dashboard/project/mjvuzsizjlcalyfmbquy/functions
• Database: https://supabase.com/dashboard/project/mjvuzsizjlcalyfmbquy/editor
• Auth: https://supabase.com/dashboard/project/mjvuzsizjlcalyfmbquy/auth/users

---

3. auth-diagnostics — Ferramenta de Diagnóstico

Edge Function: supabase/functions/auth-diagnostics/index.ts

4 ações disponíveis para teste:

admin_whoami

Valida o cookie olp_auth e retorna o payload do JWT:

const result = await invokeAction('auth-diagnostics', 'admin_whoami', {})
// → { id, nome_completo, principal_role, escola_id, roles }

Quando usar: Verificar se o token do sistema está válido.

admin_rls_smoke

Valida o token E testa se o PostgREST aceita o JWT como Bearer:

const result = await invokeAction('auth-diagnostics', 'admin_rls_smoke', {})
// → { olp_auth_ok, postgrest_ok, postgrest_error, user, sample }

Quando usar: Verificar se RLS está funcionando com o token OLP.

portal_whoami

Valida o cookie olp_mural e retorna payload do mural:

const result = await invokeAction('auth-diagnostics', 'portal_whoami', {})
// → { sub, tipo, nome_completo, escola_id, serie_id, turma_id, escopo }

Quando usar: Verificar se o token do portal (aluno/responsável) está válido.

public_smoke

Testa conectividade do PostgREST sem autenticação:

const result = await invokeAction('auth-diagnostics', 'public_smoke', {})
// → { postgrest_ok, postgrest_error, sample }

Quando usar: Verificar se o Supabase está acessível.

---

4. Problemas Frequentes

Cookie não enviado (401)

Sintoma: Todas as chamadas autenticadas retornam 401.

Checklist:

1. credentials: 'include' está no fetch? (O helper invokeAction já faz isso)
2. O domínio está em ALLOWED_ORIGINS do cors-helpers.ts?
3. O cookie olp_auth existe? (DevTools → Application → Cookies)
4. O JWT expirou? (8h para sistema, 2h para portal)

Origin não permitida (CORS)

Sintoma: Access-Control-Allow-Origin error no console.

Checklist:

1. Verificar ALLOWED_ORIGINS em supabase/functions/_shared/cors-helpers.ts
2. Origins permitidas:
   • http://localhost:5173
   • http://localhost:8080
   • https://b4188062-97f3-4ab8-aba4-214ee32684a0.lovableproject.com
   • https://id-preview--b4188062-97f3-4ab8-aba4-214ee32684a0.lovable.app
   • https://olp.digital
3. NUNCA usar '*' com credentials: 'include'

Papel insuficiente (403)

Sintoma: Usuário autenticado mas recebe "Acesso negado".

Checklist:

1. Verificar principal_role no JWT (usar admin_whoami)
2. Verificar array de papéis na Edge Function
3. Verificar se o papel está na hierarquia correta

data undefined no frontend

Sintoma: result.data é undefined mas result.success é true.

Causa: Backend retorna campo com nome diferente ou não retorna data.

Solução: Verificar resposta da Edge Function — sempre usar result.data.

Toast genérico (sem mensagem do backend)

Sintoma: Toast mostra "Erro" sem detalhes.

Solução: Usar response.message no catch do hook:

throw new Error(result.message || 'Erro genérico')

---

5. Verificar Geolocalização

Conferir se logs têm geodados

SELECT 
  COUNT(*) FILTER (WHERE cidade IS NOT NULL) as com_geo,
  COUNT(*) FILTER (WHERE cidade IS NULL) as sem_geo
FROM logs_transacoes
WHERE criado_em >= NOW() - INTERVAL '7 days';

Se geolocalização está ausente

1. Verificar se req: req está sendo passado no registrarLog()
2. Verificar se o Cloudflare Worker está injetando headers X-Geo-*

---

6. Debug de CRON Jobs

Job não executou

1. Verificar cron_status:

   SELECT * FROM cron_status ORDER BY ultima_execucao DESC;

2. Verificar se o CRON está configurado no Supabase Dashboard
3. Verificar logs: filtrar por faturamento.* ou manutencao.* em logs_transacoes

Job em estado CRÍTICO

1. Verificar ultimo_erro e tentativas_consecutivas em cron_status
2. Resolver o problema raiz
3. Executar trigger manual via Monitor CRON para resetar

---

Referências

• supabase/functions/auth-diagnostics/index.ts — Ferramenta de diagnóstico
• supabase/functions/_shared/cors-helpers.ts — Origins permitidas
• docs/security/RATE_LIMITS.md — Detalhes de rate-limits
• docs/security/AUDIT_LOG.md — Como interpretar logs
• docs/operations/CRON_JOBS.md — Detalhes dos jobs CRON