AgrSis Docs
Troubleshooting

Health Check - Proteção contra API Offline

Health Check - Proteção contra API Offline

📋 Visão Geral

Sistema de health check implementado para evitar que o frontend carregue com erros quando a API estiver offline ou em deploy.

🎯 Como Funciona

1. Endpoint de Health na API

  • Rota: GET /api/health
  • Resposta: { "status": "ok", "timestamp": "..." }
  • Sem autenticação (rota pública)
  • Muito rápido (não acessa banco de dados)

2. Plugin de Health Check (Frontend)

Cada frontend (Producer e Supplier) possui um plugin Nuxt que:

  1. Executa ANTES de carregar a aplicação (enforce: 'pre')
  2. Tenta conectar na API com timeout de 2 segundos
  3. Se API estiver OK: Carrega normalmente
  4. Se API estiver offline: Redireciona para /maintenance.html

3. Página de Manutenção

  • Localização: apps/producer/public/maintenance.html e apps/supplier/public/maintenance.html
  • Auto-reload: Tenta reconectar na API a cada 5 segundos
  • Quando API volta: Redireciona automaticamente para a página principal

⚡ Performance

Otimizado para Docker (mesma rede)

  • Timeout: 2 segundos (muito curto!)
  • URL interna: http://agrsis_api:8000 (comunicação entre containers)
  • Sem latência de rede externa

Impacto no Carregamento

  • API OK: Adiciona ~200-500ms no carregamento inicial
  • API offline: Redireciona imediatamente para manutenção (sem erros)

🔧 Arquivos Envolvidos

Backend (API)

apps/api/routes/api.php
├── Linha 32-37: Rota GET /api/health

Frontend Producer

apps/producer/
├── plugins/health-check.client.ts    # Plugin de verificação
└── public/maintenance.html            # Página de manutenção

Frontend Supplier

apps/supplier/
├── plugins/health-check.client.ts    # Plugin de verificação
└── public/maintenance.html            # Página de manutenção

🧪 Como Testar

1. Testar API Online (funcionamento normal)

# API deve estar rodando
docker --context orbstack ps | grep agrsis_api

# Acessar frontend normalmente
# - Producer: http://localhost:3003
# - Supplier: http://localhost:3004

# Console do browser deve mostrar:
# 🔍 Health Check: Verificando disponibilidade da API...
# ✅ Health Check: API disponível { status: 'ok', timestamp: '...' }

2. Testar API Offline (página de manutenção)

# Parar container da API
docker --context orbstack stop agrsis_api

# Acessar frontend
# - Producer: http://localhost:3003
# - Supplier: http://localhost:3004

# Deve redirecionar automaticamente para /maintenance.html
# Console do browser deve mostrar:
# 🔍 Health Check: Verificando disponibilidade da API...
# ❌ Health Check: API indisponível ou em manutenção

# Religar API
docker --context orbstack start agrsis_api

# Página de manutenção reconecta automaticamente após ~5 segundos

3. Testar Endpoint Health Diretamente

# Teste manual do endpoint
curl http://localhost:8000/api/health

# Resposta esperada:
# {"status":"ok","timestamp":"2026-01-28T00:42:42.363781Z"}

🚀 Deploy em Produção

VPS - Nginx Proxy Manager

Na VPS, o Nginx Proxy Manager já está configurado para servir página de manutenção quando containers estão down:

# Configuração NPM (já existe)
error_page 502 503 504 /maintenance.html;
location = /maintenance.html {
    root /opt/agrsis/maintenance;
    internal;
}

Fluxo em Produção

  1. Deploy inicia → API vai down temporariamente
  2. NPM detecta → Serve /opt/agrsis/maintenance/index.html
  3. Usuário vê página de manutenção → Sem erros!
  4. Deploy termina → API volta
  5. Página de manutenção reconecta → Redireciona automaticamente

🐛 Troubleshooting

Plugin não está executando

Sintoma: Frontend carrega mesmo com API offline

Solução:

# Verificar se arquivo existe
ls apps/producer/plugins/health-check.client.ts
ls apps/supplier/plugins/health-check.client.ts

# Limpar cache do Nuxt
rm -rf apps/producer/.nuxt
rm -rf apps/supplier/.nuxt

# Reiniciar dev server
docker compose restart agrsis_producer
docker compose restart agrsis_supplier

Redireciona mas página de manutenção não carrega

Sintoma: Redireciona para /maintenance.html mas mostra 404

Solução:

# Verificar se arquivo existe em public/
ls apps/producer/public/maintenance.html
ls apps/supplier/public/maintenance.html

# Se não existir, criar novamente (ver seção "Arquivos")

Timeout muito lento

Sintoma: Demora muito para detectar que API está offline

Solução: Ajustar timeout no plugin (linha 22):

// Reduzir de 2000ms para 1000ms se necessário
const timeoutId = setTimeout(() => controller.abort(), 1000)

Console mostra erro CORS

Sintoma: CORS error ao fazer fetch do health check

Solução: Health check usa fetch nativo, sem passar pelo axios configurado. Verificar se API permite CORS:

# No container da API
docker --context orbstack exec agrsis_api cat config/cors.php | grep paths

📊 Logs de Debug

Console do Browser (Desenvolvimento)

// API OK
🔍 Health Check: Verificando disponibilidade da API...
✅ Health Check: API disponível {status: "ok", timestamp: "2026-01-28T00:42:42.363781Z"}

// API Offline
🔍 Health Check: Verificando disponibilidade da API...
❌ Health Check: API indisponível ou em manutenção Error: Failed to fetch

Logs da API (se quiser adicionar)

# Ver logs da API em tempo real
docker --context orbstack logs agrsis_api -f | grep health

✅ Checklist de Implementação

  • Endpoint /api/health criado na API
  • Plugin health-check.client.ts no Producer
  • Plugin health-check.client.ts no Supplier
  • Página maintenance.html no Producer
  • Página maintenance.html no Supplier
  • Timeout otimizado (2 segundos)
  • Auto-reconnect a cada 5 segundos
  • Testes locais realizados
  • Deploy em produção
  • Testar em produção com deploy real

🔄 Próximos Passos (Opcional)

Melhorias Futuras

  1. Health Check Completo
    • Verificar conexão com banco de dados
    • Verificar Redis
    • Verificar permissões de storage
  2. Retry com Backoff
    • 1ª tentativa: 2s
    • 2ª tentativa: 4s
    • 3ª tentativa: 8s
  3. Métricas de Uptime
    • Registrar downtime no banco
    • Dashboard de status (status.agrsis.com)
  4. Notificações
    • Avisar admin via WhatsApp quando API cair
    • Integrar com monitoramento (UptimeRobot)

Última atualização: 2026-01-28 Versão: 1.0 Status: ✅ Implementado e testado

🔴 PROBLEMAS DE BUILD - FRONTENDS

Data: 2026-01-13 Status: ✅ PRODUCER RESOLVIDO | ⏳ SUPPLIER PENDENTE

Arquitetura

Materiais de arquitetura e decisões técnicas.

Copyright © 2026