Guide de dépannage¶

Ce guide complet de dépannage couvre les problèmes courants rencontrés lors du développement, du déploiement et de la maintenance d’AMRnet.

Problèmes de performance¶

Chargement lent des données (2+ de minutes de charge)¶

Symptômes: - Les données de E. coli prennent 3+ minutes à charger - K. pneumoniae en prenant 2+ minutes - Gelage du navigateur lors de la récupération de données - Grandes tailles de charge (75MB+)

Script de diagnostic :

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

Causses racines: - Requêtes non-officialisées MongoDB renvoyant tous les champs - Grands ensembles de données (227K+ documents pour E. coli) - Single monolithic API calls - Manque de pagination ou chargement progressif

Solutions :

Utiliser les points terminaux optimisés :

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

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

Implémenter la pagination pour les grands ensembles de données :

// 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`);
};

Utiliser le chargement parallèle :

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

Validation des performances :

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

Gel du navigateur sur les jeux de données volumineux¶

Symptômes: - Le navigateur ne répond plus - L’interface utilisateur bloque pendant le traitement des données - Avertissements « Page non réactive»

Diagnostic :

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

Solutions :

Chargement progressif du génotype :

// 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);
};

Travailleurs Web pour le traitement lourd :

// 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);
};

Validation :

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

Problèmes de développement¶

Erreurs ESLint et avertissements¶

Symptômes : - Échecs de compilation dus aux erreurs de linting - Avertissements de variables inutilisés - Import/export erreurs

Réparation Rapide :

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

Corrections manuelles :

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

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

Problèmes et corrections courants:

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

Problèmes de connexion MongoDB¶

Symptômes: - « Impossible de charger la ressource: 500 Erreur interne du serveur » - Délai de connexion - Échec d’authentification

Diagnostic :

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

Solutions communes:

Vérifier les variables d’environnement :

# Verify configuration
echo $MONGODB_URI
echo $NODE_ENV

Corriger le format de la chaîne de connexion :

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

Tester la connexion avec une nouvelle tentative Logic:

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

Problèmes de démarrage du serveur¶

Symptômes: - Le serveur ne démarre pas sur le port correct - Erreurs de port « EADDRINUSE » - Erreurs de syntaxe d’import/export

Solutions :

Configuration du port :

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

Processus existants de Kill Existant:

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

Utiliser le serveur de test minimal:

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

Validation :

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

Problèmes de déploiement¶

Échec du déploiement de Heroku¶

Symptômes: - Pannes de construction pendant le déploiement - Limite de mémoire dépassée - Temps de réponse lent

Vérification du pré-déploiement :

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

Corrections courantes :

Variables d’environnement :

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

Optimiser pour Heroku :

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

Problèmes de Build Script :

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

Performance de l’Atlas MongoDB¶

Symptômes: - Connexions à haute latence - Erreurs de délai - Faible performance de requête

Diagnostic :

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

Optimisations :

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

Regroupement de connexions:

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

Traduction et internationalisation¶

Problèmes de flux de travail de traduction¶

Symptômes: - Clés de traduction manquantes - Workflow de traduction non déclenché - Erreurs de syntaxe JSON

Validation :

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

Corrections courantes :

Structure du fichier:

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

Validation 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'

Problèmes de qualité de code¶

Nettoyage et maintenance¶

Symptômes: - Excès de console.log - Code commenté - Fichiers et dépendances inutilisés

Nettoyage automatisé:

# Run comprehensive cleanup
./scripts/cleanup.sh

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

Nettoyage manuel :

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

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

Problèmes de sécurité¶

Symptômes : - Identifiants exposés dans le dépôt - Avertissements de sécurité - Dépendances vulnérables

Actions immédiates:

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

# Security audit
npm audit

# Fix vulnerabilities
npm audit fix

Prévention :

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

Optimisation des performances¶

Surveillance et validation¶

Surveillance en temps réel :

# Monitor performance
node scripts/monitor-performance.js

Test de la charge :

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

Benchmarks de performance :

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

Résultats attendus : - K. pneumoniae: <2s load time - E. coli: <7s with pagination - E. coli (diarrheagenic): <3s load time - Payload reduction: 60-90%

Référence des scripts de diagnostic¶

Diagnostics Rapide:

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

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

# Deployment readiness
node scripts/deployment-readiness.js

Analyse complète :

# 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

Vérifications de statut:

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

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

Procédures d’urgence¶

Problèmes critiques de performance¶

Si les utilisateurs rapportent plus de 2 minutes de temps de chargement :

Réponse immédiate :

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

Vérifier la correction :

node scripts/post-fix-validation.js

Résultats du suivi :

node scripts/monitor-performance.js

Urgence du Serveur Bas¶

Si le serveur ne répond pas :

Démarrer le serveur minimal :

node scripts/minimal-server.js

Journal de vérification:

heroku logs --tail

Redémarrer avec la configuration fixe :

node scripts/server-fixed.js

Obtenir de l’aide¶

Quand utiliser chaque script:

Problèmes de performance : organism-performance-debugger.js
Problèmes de déploiement : deployment-readiness.js
Problèmes MongoDB : test-fixie-connection.js
Qualité du code : cleanup_script.sh
Problèmes de traduction : test-translation-setup.sh

Support de la communauté: - Problèmes GitHub : https://github.com/amrnet/amrnet/issues - Discussions: https://github.com/amrnet/amrnet/discussions - Email: amrnetdashboard@gmail.com

Contacts d’urgence: - bugs critiques : problèmes GitHub avec étiquette « urgent » - Problèmes de sécurité : amrnetdashboard@gmail.com