Guía de solución de problemas¶

Esta guía completa de solución de problemas cubre los problemas comunes encontrados en el desarrollo, despliegue y mantenimiento de AMRnet.

Problemas de rendimiento¶

Carga lenta de datos (2+ minutos de carga)¶

Síntomas: - Datos de E. coli que tardan más de 3 minutos en cargar - K. pneumoniae tardando 2+ minutos - Navegador congelado durante la obtención de datos - Tamaños grandes de carga útil (75MB+)

Diagnóstico Script:

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

Causas de root: - Las consultas de MongoDB no optimizadas que devuelven todos los campos - Conjuntos de datos grandes (227K+ documentos para E. coli) - Llamadas de API monolíticas únicas - falta de paginación o carga progresiva

Soluciones:

Usar puntos finales optimizados:

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

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

Implementar paginación para conjuntos de datos grandes:

// 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 carga paralela:

// 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')
]);

Validación de rendimiento:

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

Congelación del navegador en conjuntos de datos grandes¶

Symptoms: - Navegador se vuelve poco sensible - Interfaz de usuario se congela durante el procesamiento de datos - advertencias «Page Unresponsive»

Diagnóstico:

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

Soluciones:

Carga progresiva 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);
};

Trabajadores Web para el procesamiento 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);
};

Validación:

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

Problemas de desarrollo¶

Avisos y errores ESLint¶

Symptoms: - Build failures due to linting errors - Unused variable warnings - Importe/export errors

Corrección rápida:

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

Correcciones manuales:

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

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

Problemas y arreglos comunes:

// 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 conexión de MongoDB¶

Symptoms: - «Error al cargar el recurso: 500 Error interno del servidor» - Tiempo de espera de conexión - Fallos de autenticación

Diagnóstico:

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

Soluciones comunes:

Comprobar variables de entorno:

# Verify configuration
echo $MONGODB_URI
echo $NODE_ENV

Fijar formato de cadena de conexión:

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

Prueba de conexión con la lógica de reintento:

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 inicio del servidor¶

Sintomas: - Servidor que no comienza en el puerto correcto - errores de puerto «EADDRINUSE» - Importar/exportar errores de sintaxis

Soluciones:

Configuración del puerto:

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

Matar procesos existentes:

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

Usar servidor mínimo de prueba:

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

Validación:

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

Problemas de despliegue¶

Fallos de Despliegue de Heroku¶

Síntomas: - Construir fallos durante la implementación - Límite de memoria excedido - Veces de respuesta lenta

Comprobación de preimplementación:

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

Arreglos comunes:

Variables de entorno:

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

Optimizar para Heroku:

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

Build Script Issues:

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

Desempeño Atlas de MongoDB¶

Síntomas: - Conexiones de alta latencia - Errores de espera - Pobre rendimiento de la consulta

Diagnóstico:

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

Optimizaciones:

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

Conexión combinando:

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

Traducción e Internacionalización¶

Problemas de flujo de trabajo de traducción¶

Síntomas: - Faltan claves de traducción - Flujo de trabajo de traducción no desencadenando - errores de sintaxis JSON

Validación:

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

Arreglos comunes:

Estructura de archivo:

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

Validación 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'

Calidad del código de problemas¶

Limpieza y mantenimiento¶

Symptoms: - Excesivas declaraciones console.log - Código comentado - Archivos no utilizados y dependencias

Limpieza automática:

# Run comprehensive cleanup
./scripts/cleanup.sh

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

Limpieza 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 seguridad¶

Symptoms: - Credenciales expuestas en el repositorio - Avisos de seguridad - Dependencias vulnerables

Acciones inmediatas:

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

# Security audit
npm audit

# Fix vulnerabilities
npm audit fix

Prevención:

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

Optimización de rendimiento¶

Monitoreo y validación¶

Monitoreo en tiempo real:

# Monitor performance
node scripts/monitor-performance.js

Prueba de Carga:

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

Marcas de Rendimiento:

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

Resultados esperados: - K. pneumoniae: <2s load time - E. coli: <7s with pagination - E. coli (diarrheagenica): <3s load time - Payload reduction: 60-90%

Referencia de Diagnósticos¶

Diagnóstico rápido:

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

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

# Deployment readiness
node scripts/deployment-readiness.js

Análisis exhaustivo:

# 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

Comprobaciones de Estado:

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

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

Procedimientos de emergencia¶

Problemas de rendimiento crítico¶

Si los usuarios reportan 2+ minutos de tiempo de carga:

Respuesta inmediata:

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

Verificar la solución:

node scripts/post-fix-validation.js

Controlar resultados:

node scripts/monitor-performance.js

Emergencia Abajo del Servidor¶

Si el servidor no responde:

Iniciar servidor mínimo:

node scripts/minimal-server.js

Registros de verificación:

heroku logs --tail

Reinicia con la configuración fija:

node scripts/server-fixed.js

Obteniendo ayuda¶

Cuándo usar cada Script:

Problemas de rendimiento: organism-performance-debugger.js
Problemas de despliegue: deployment-readiness.js
Problemas de MongoDB: test-fixie-connection.js
Calidad del código: cleanup_script.sh
Problemas de traducción: test-translation-setup.sh

Soporte de la comunidad: - Problemas de GitHub: https://github.com/amrnet/amrnet/issues - Discusiones: https://github.com/amrnet/amrnet/discussions - Email: amrnetdashboard@gmail.com

Contactos de emergencia: - Errores críticos: Problemas de GitHub con etiqueta «urgente» - Problemas de seguridad: amrnetdashboard@gmail.com