Guia para solução de problemas¶

Este guia abrangente de solução de problemas abrange problemas comuns encontrados ao desenvolver, implantar e manter a AMRnet. As soluções são baseadas em problemas do mundo real e suas correções testadas.

Problemas de Desempenho¶

Carregamento lento de dados (2+ Tempo de carregamento de minutos)¶

Symptoms: - E. coli dados demorando 3 minutos para carregar - K. pneumoniae leva 2 minutos - Congelando o navegador durante a busca de dados - tamanhos grandes do payload (75MB+)

Diagnosis Script:

# Test performance issues
node scripts/organism-performance-debugger.js

Causas Raiz: - Consultas MongoDB não otimizadas retornando todos os campos - datasets grandes (227K+ documentos para E. coli) - Chamadas únicas de API monolítica - falta de paginação ou carregamento progressivo

Soluções:

Use pontos de extremidade otimizados:

// Instead of:
const data = await axios.get('/api/getDataForEcoli'); // 186MB, 21s

// Use:
const data = await axios.get('/api/optimized/map/ecoli'); // 13MB, 7s

Paginação de Implementação para Big Datasets:

// For E. coli (large dataset)
const firstPage = await axios.get('/api/optimized/paginated/ecoli?page=1&limit=5000');

// Progressive loading
const loadNextPage = async (page) => {
  return axios.get(`/api/optimized/paginated/ecoli?page=${page}&limit=5000`);
};

Usar carregamento paralelo:

// Load multiple chart sections simultaneously
const [mapData, trendsData, resistanceData] = await Promise.all([
  axios.get('/api/optimized/map/ecoli'),
  axios.get('/api/optimized/trends/ecoli'),
  axios.get('/api/optimized/resistance/ecoli')
]);

Validação do desempenho:

# Test the fixes
node scripts/real-performance-test.js

Congelamento do navegador em grandes conjuntos de dados¶

Symptoms: - O navegador se torna não responsivo - UI congela durante o processamento de dados - avisos de «Page Unresponsive»

Diagnóstico:

# Test for freezing issues
node scripts/ecoli-freeze-debugger.js

Soluções:

Carregamento Progressivo de Genotipo:

// Prevent freezing with requestIdleCallback
const processGenotypesProgressively = (data) => {
  const batches = chunkArray(data, 1000);
  let processed = [];

  const processBatch = (batchIndex) => {
    if (batchIndex >= batches.length) {
      updateUI(processed);
      return;
    }

    requestIdleCallback(() => {
      processed = [...processed, ...batches[batchIndex]];
      processBatch(batchIndex + 1);
    });
  };

  processBatch(0);
};

Trabalhadores da Web para o Processamento Pesado:

// offload heavy data processing
const worker = new Worker('/workers/data-processor.js');

worker.postMessage({ data: largeDataset });
worker.onmessage = (event) => {
  const processedData = event.data;
  updateUI(processedData);
};

Validação:

# Verify fix is working
node scripts/post-fix-validation.js

Problemas de desenvolvimento¶

ESLint Erros e Avisos¶

Sintomas: - Criar falhas devido a erros de linhagem - avisos variáveis não utilizados - Importar/exportar erros

Correção rápida:

# Automated ESLint fixes
./scripts/comprehensive-eslint-fix.sh

Correções manuais:

# Fix specific issues
cd client
npx eslint src --fix --max-warnings 200

# For development (bypass errors)
ESLINT_NO_DEV_ERRORS=true npm start

Problemas e correções comuns:

// Fix unused theme parameters
// Before:
const useStyles = makeStyles((theme) => ({
  root: { padding: 16 }
}));

// After:
const useStyles = makeStyles((_theme) => ({
  root: { padding: 16 }
}));

// Fix unused parameters in catch blocks
// Before:
.catch((error) => console.log('Error occurred'))

// After:
.catch((_error) => console.log('Error occurred'))

Problemas de conexão MongoDB¶

Symptoms: - «Falha ao carregar recurso: 500 Erro Interno do Servidor» - Exceções na conexão - Falhas de autenticação

Diagnóstico:

# Test MongoDB connection
node scripts/test-fixie-connection.js

Soluções comuns:

Verifique as Variáveis de Ambiente:

# Verify configuration
echo $MONGODB_URI
echo $NODE_ENV

Corrigir formato String da conexão:

# Correct format
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/dbname?retryWrites=true&w=majority

Testar Conexão com Lógica:

const connectWithRetry = async () => {
  const maxRetries = 3;
  let retries = 0;

  while (retries < maxRetries) {
    try {
      await client.connect();
      return;
    } catch (error) {
      retries++;
      console.log(`Connection attempt ${retries} failed: ${error.message}`);
      if (retries === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
};

Problemas de Inicialização¶

Symptoms: - Servidor não iniciando na porta correta - erros nas portas «EADDRINUSE» - Erros de sintaxe importar/exportar

Soluções:

Configuração de Porta:

# Start on specific port
PORT=8080 node server.js

Processos de Morte Existentes:

# Find and kill processes using port
lsof -ti:8080 | xargs kill -9

Usar Servidor de Teste Mínimo:

# Start minimal server for testing
node scripts/test-server.js

Validação:

# Test server endpoints
./scripts/test-api.sh

Problemas de implantação¶

Falha na implantação do Heroku¶

Sintomas: - Construa falhas durante a implantação - excedido o limite de memória - Tempos de resposta lentos

Verificação de pré-implantação:

# Validate deployment readiness
node scripts/deployment-readiness.js

Correções comuns:

Variáveis de ambiente:

# Set required variables
heroku config:set NODE_ENV=production
heroku config:set MONGODB_URI="your-connection-string"

Otimizar para o Heroku:

# Run Heroku-specific optimizations
node scripts/heroku-atlas-optimizer.js

Problemas de Script de Construção:

// package.json
{
  "scripts": {
    "heroku-postbuild": "cd client && npm install && npm run build"
  }
}

Desempenho do Atlas MongoDB¶

Sintomas: - Conexões de alta latência - Erros de tempo limite - Desempenho de consultas ruins

Diagnóstico:

# Check Atlas performance
node scripts/heroku-atlas-optimizer.js

Otimizações:

1. Region Proximity: - Ensure Heroku and Atlas are in same region - Use us-east-1 for both services

Banco de Conexão:

const mongoOptions = {
  maxPoolSize: 10,
  minPoolSize: 5,
  maxIdleTimeMS: 30000,
  serverSelectionTimeoutMS: 5000,
  socketTimeoutMS: 45000
};

Tradução e Internacionalização¶

Problemas de workflow de tradução¶

Symptoms: - Chaves de tradução ausentes - O fluxo de trabalho de tradução não aciona - erros de sintaxe JSON

Validação:

# Test translation setup
./scripts/test-translation-setup.sh

Correções comuns:

Estrutura de Arquivos:

# Ensure correct structure
client/
├── locales/
│   ├── en.json
│   ├── fr.json
│   ├── pt.json
│   └── es.json
└── src/
    └── i18n.js

Validação JSON:

# Validate JSON files
python3 -m json.tool client/locales/en.json

GitHub Workflow:

# .github/workflows/translate_app.yml
name: Auto-translate Application
on:
  push:
    paths:
      - 'client/locales/en.json'

Problemas de Qualidade do Código¶

Limpeza e manutenção¶

Symptoms: - Excessivas console.log - Código Commented-out - Dependências e arquivos não usados

Limpeza automatizada:

# Run comprehensive cleanup
./scripts/cleanup.sh

# Code-specific cleanup
./scripts/cleanup_script.sh

Limpeza manual:

# Remove debugging code
find . -name "*.js" | xargs grep -l "console.log" | head -10

# Find commented code
find . -name "*.js" | xargs grep -l "^[[:space:]]*//.*TODO"

Problemas de Segurança¶

Symptoms: - Credenciais expostas no repositório - Alertas de segurança - Dependências vulneráveis

Ações imediatas:

# Check for exposed secrets
git log --all --full-history -- .env*

# Security audit
npm audit

# Fix vulnerabilities
npm audit fix

Prevenção:

# .gitignore
.env
.env.*
!.env.example

Otimização de desempenho¶

Monitoramento e validação¶

Monitoramento em tempo real:

# Monitor performance
node scripts/monitor-performance.js

Carregar Testes:

# Test endpoint performance
node scripts/test-optimized-endpoints.js

Marcadores de desempenho:

# Comprehensive performance test
node scripts/test-performance.js

Resultados esperados: - K. pneumoniae: <2s tempo de carregamento - E. coli: <7s com paginação - E. coli (diarreia): <3s tempo de carregamento - Redução de carga: 60-90%

Referência de Scripts Diagnósticos¶

Diagnósticos rápidos:

# Health check
curl http://localhost:8080/api/health

# Performance check
node scripts/real-performance-test.js

# Deployment readiness
node scripts/deployment-readiness.js

Análise abrangente:

# Full performance analysis
node scripts/organism-performance-debugger.js

# Heroku/Atlas optimization
node scripts/heroku-atlas-optimizer.js

# Translation validation
./scripts/test-translation-setup.sh

Verificação de status:

# Project status
./scripts/status-check.sh

# API endpoints test
./scripts/test-api.sh

Procedimentos de Emergência¶

Problemas de Desempenho Crítico¶

Se usuários relatam tempo de carregamento de 2 + minutos:

Resposta Imediata:

# Switch to optimized endpoints
# Update frontend API calls from /api/ to /api/optimized/

Correção de Verificação:

node scripts/post-fix-validation.js

Resultados do Monitor:

node scripts/monitor-performance.js

Emergência do servidor para baixo¶

Se o servidor não estiver respondendo:

Iniciar servidor mínimo:

node scripts/minimal-server.js

Verificar registros:

heroku logs --tail

Reiniciar com configuração fixa:

node scripts/server-fixed.js

Obtendo ajuda¶

Quando usar cada Script:

Problemas de desempenho: organism-performance-debugger.js
Problemas de implantação: deployment-readiness.js
Problemas do MongoDB: test-fixie-connection.js
Qualidade do código: cleanup_script.sh
Problemas de tradução: test-translation-setup.sh

Suporte da Comunidade: - Problemas no GitHub: https://github.com/amrnet/amrnet/issues - Discussões: https://github.com/amrnet/amrnet/discussions - Email: amrnetdashboard@gmail.com

Contatos de emergência: - Problemas críticos: o GitHub com a etiqueta «urgente» - Problemas de segurança: amrnetdashboard@gmail.com