Solução de Problemas

Este guia ajuda a resolver problemas comuns encontrados com o PCH-SIG.

Diagnóstico rápido

Verificar o estado dos serviços

# Estado dos contêineres
docker ps -a

# Saúde da aplicação
curl http://localhost:8000/api/health

Script de diagnóstico

# diagnostic.ps1
Write-Host "=== Diagnóstico PCH-SIG ===" -ForegroundColor Cyan

# Docker
Write-Host "`n[Docker]"
docker-machine status default

# Contêineres
Write-Host "`n[Contêineres]"
docker-machine ssh default "docker ps --format 'table {{.Names}}\t{{.Status}}'"

# Portas
Write-Host "`n[Portas]"
netsh interface portproxy show all

# Testes
Write-Host "`n[Testes]"
try {
    Invoke-WebRequest -Uri "http://localhost:3000" -UseBasicParsing -TimeoutSec 5 | Out-Null
    Write-Host "Frontend: OK" -ForegroundColor Green
} catch {
    Write-Host "Frontend: ERRO" -ForegroundColor Red
}

try {
    Invoke-WebRequest -Uri "http://localhost:8000/api" -UseBasicParsing -TimeoutSec 5 | Out-Null
    Write-Host "API: OK" -ForegroundColor Green
} catch {
    Write-Host "API: ERRO" -ForegroundColor Red
}

---

Problemas de conexão

"Connection refused" no frontend

Sintomas: O navegador exibe "Connection refused" em http://localhost:3000

Causas possíveis:

1. Contêiner frontend não iniciado
2. Proxy de porta não configurado

Soluções:

# Verificar o contêiner
docker ps | grep pch_frontend

# Se parado, reiniciar
docker start pch_frontend

# Verificar o proxy de porta
netsh interface portproxy show v4tov4

# Reconfigurar se necessário
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=80 connectaddress=192.168.99.100

"502 Bad Gateway" na API

Sintomas: As requisições API retornam erro 502

Causas possíveis:

1. Backend PHP não iniciado
2. Nginx backend mal configurado

Soluções:

# Verificar os contêineres
docker ps | grep -E "(pch_backend|pch_nginx_backend)"

# Consultar os logs
docker logs pch_backend --tail 50
docker logs pch_nginx_backend --tail 50

# Reiniciar
docker restart pch_backend pch_nginx_backend

"401 Unauthorized"

Sintomas: Todas as requisições API retornam 401

Causas possíveis:

1. Token JWT expirado
2. Chaves JWT inválidas

Soluções:

# Verificar as chaves JWT
docker exec pch_backend ls -la config/jwt/

# Regenerar as chaves
docker exec pch_backend php bin/console lexik:jwt:generate-keypair --overwrite

# Limpar o cache
docker exec pch_backend php bin/console cache:clear

---

Problemas de banco de dados

"Connection refused" PostgreSQL

Sintomas: Erro de conexão com o banco de dados

Soluções:

# Verificar o contêiner
docker ps | grep pch_postgres

# Verificar os logs
docker logs pch_postgres --tail 50

# Testar a conexão
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "SELECT 1;"

"Relation does not exist"

Sintomas: Erro "relation X does not exist"

Causa: Migrações não executadas

Solução:

# Executar as migrações
docker exec pch_backend php bin/console doctrine:migrations:migrate --no-interaction

# Verificar o esquema
docker exec pch_backend php bin/console doctrine:schema:validate

Banco de dados corrompido

# Verificar a integridade
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "
SELECT 'menages' as table_name, count(*) FROM menages
UNION ALL
SELECT 'beneficiaires', count(*) FROM beneficiaires
UNION ALL
SELECT 'paiements', count(*) FROM paiements;"

# Se houver problema, restaurar do backup
docker exec -i pch_postgres psql -U pch_admin -d pch_sig < backup.sql

---

Problemas Docker

Docker Machine não inicia

# Verificar VirtualBox
& "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" list vms

# Iniciar manualmente
docker-machine start default

# Se houver erro, regenerar certificados
docker-machine regenerate-certs default

Contêiner em reinício contínuo

Sintomas: Contêiner com status "Restarting"

# Ver os logs
docker logs pch_backend

# Causas comuns:
# - Erro de configuração
# - Dependência faltando
# - Permissões incorretas

# Iniciar em modo interativo para debug
docker-compose run --rm backend bash

Espaço em disco insuficiente

# Verificar o espaço
docker system df

# Limpar
docker system prune -a --volumes

---

Problemas de desempenho

Aplicação lenta

Diagnóstico:

# Verificar o uso de recursos
docker stats

# Consultas PostgreSQL lentas
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY total_time DESC
LIMIT 10;"

Soluções:

# Limpar o cache Redis
docker exec pch_redis redis-cli -a redis_secure_2025 FLUSHALL

# Otimizar PostgreSQL
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "VACUUM ANALYZE;"

# Limpar o cache Symfony
docker exec pch_backend php bin/console cache:clear --env=prod

Memória insuficiente

# Aumentar a memória do contêiner em docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G

---

Problemas de autenticação

Impossível fazer login

Verificações:

# Verificar que o usuário existe
docker exec pch_postgres psql -U pch_admin -d pch_sig -c "
SELECT email, roles, is_active FROM users WHERE email = 'admin@pch-sig.sn';"

# Redefinir a senha
docker exec pch_backend php bin/console app:reset-password admin@pch-sig.sn NovaSenha123!

Token JWT inválido

# Verificar as chaves
docker exec pch_backend ls -la config/jwt/

# Verificar as permissões
docker exec pch_backend stat config/jwt/private.pem

# Regenerar
docker exec pch_backend php bin/console lexik:jwt:generate-keypair --overwrite

---

Problemas frontend

Página em branco

Causas possíveis:

1. Build faltando
2. Erro JavaScript

Soluções:

# Verificar o build
ls -la frontend/build/

# Reconstruir
cd frontend
npm run build

# Verificar o console do navegador (F12)

Service Worker bloqueando atualizações

// Forçar a atualização
// No console do navegador
navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for(let registration of registrations) {
        registration.unregister();
    }
});

Ou incrementar a versão em service-worker.js:

const CACHE_NAME = 'pch-sig-cache-v3';

Erros CORS

Sintomas: Erro "CORS policy" no console

Soluções:

# Verificar a configuração CORS
docker exec pch_backend cat .env | grep CORS

# Modificar se necessário
CORS_ALLOW_ORIGIN='^https?://(localhost|192\.168\.1\.*)(:[0-9]+)?$'

# Reiniciar
docker restart pch_backend

---

Problemas de arquivos

Upload falha

# Verificar as permissões
docker exec pch_backend ls -la public/uploads/

# Corrigir
docker exec pch_backend chown -R www-data:www-data public/uploads/
docker exec pch_backend chmod -R 775 public/uploads/

Arquivos não acessíveis

# Verificar o mapeamento de volumes
docker inspect pch_backend | grep -A 10 Mounts

# Verificar que o arquivo existe
docker exec pch_backend ls -la public/uploads/documents/

---

Comandos úteis

Reiniciar tudo

docker-machine ssh default "cd /c/pch-sig/deploy && docker compose restart"

Limpar todos os caches

docker exec pch_backend php bin/console cache:clear
docker exec pch_redis redis-cli -a redis_secure_2025 FLUSHALL

Reinicializar completamente

# ATENÇÃO: Exclui todos os dados!
docker-machine ssh default "cd /c/pch-sig/deploy && docker compose down -v"
docker-machine ssh default "cd /c/pch-sig/deploy && docker compose up -d"

---

Obter ajuda

Informações a fornecer

Ao pedir ajuda, inclua:

1. Descrição do problema
2. Passos para reproduzir
3. Mensagens de erro completas
4. Logs relevantes:

   docker logs pch_backend --tail 100 > backend.log
   docker logs pch_postgres --tail 50 > postgres.log

5. Estado dos contêineres:

   docker ps -a > containers.txt

---

Próximos passos

• Logs
• Monitoramento