Aller au contenu

Résolution de problèmes - Back-Office LMELP

Problèmes courants et solutions

🔌 Problèmes de connexion

Application inaccessible (localhost:5173 ne répond pas)

Symptômes : - Page blanche ou erreur "Connexion impossible" - Message "Cette page est inaccessible" - Temps de chargement infini

Solutions :

  1. Vérifiez que le frontend est démarré : 

    # Dans le terminal
cd frontend
npm run dev

  2. Contrôlez l'URL :

  3. URL correcte : http://localhost:5173

  4. Pas https:// ni port différent

  5. Vérifiez les ports occupés :

  6. Essayez un autre port si 5173 est occupé
  7. Fermez les autres applications utilisant ce port

API Backend inaccessible

Symptômes : - Liste d'épisodes vide - Erreur "Impossible de contacter le serveur" - Erreur réseau dans la console (F12)

Solutions :

  1. Vérifiez que le backend tourne : 
    # Démarrage avec sélection automatique de port (recommandé depuis Issue #13)
PYTHONPATH=/workspaces/back-office-lmelp/src python -m back_office_lmelp.app

# Le serveur affichera automatiquement quelque chose comme :
# 🚀 Démarrage du serveur sur 0.0.0.0:54324 (port automatiquement sélectionné)

Avantages de la sélection automatique : - ✅ Aucune configuration manuelle nécessaire - ✅ Évite automatiquement les ports occupés - ✅ Le frontend trouve automatiquement le bon port

# Ou avec port spécifique si vous voulez forcer un port
PYTHONPATH=/workspaces/back-office-lmelp/src API_PORT=54322 python -m back_office_lmelp.app
  1. Testez l'API directement :
  2. Consultez le terminal backend pour voir le port automatiquement sélectionné (ex: 54324)
  3. Ouvrez : http://localhost:[PORT]/api/episodes (remplacez [PORT] par le port affiché)

  4. Vous devez voir du JSON avec les épisodes

  5. Vérifiez la découverte automatique de port :

  6. Le fichier .dev-ports.json doit être créé automatiquement à la racine du projet
  7. Il contient les informations de connexion pour le frontend

  8. En cas de problème, supprimez ce fichier et redémarrez le backend

  9. Vérifiez les logs backend :

  10. Messages d'erreur dans le terminal backend
  11. Erreurs de connexion MongoDB

💾 Problèmes de sauvegarde

"Erreur de sauvegarde - [object Object]" (RÉSOLU)

Contexte : Ce problème a été corrigé dans la version actuelle.

Cause historique : Incompatibilité format text/plain entre frontend/backend Solution appliquée : Backend modifié pour lire Request.body() correctement

Sauvegarde en cours indéfiniment

Symptômes : - Indicateur "⏳ Sauvegarde en cours..." ne disparaît pas - Modifications perdues au rechargement

Solutions :

  1. Rechargez la page :
  2. F5 ou Ctrl+R

  3. Vérifiez si les modifications sont conservées

  4. Vérifiez la connexion réseau :

  5. Console navigateur (F12) → onglet Network

  6. Recherchez les erreurs HTTP

  7. Forcez la sauvegarde :

  8. Ctrl+S dans la zone de texte
  9. Ou modifiez légèrement le texte pour relancer

Modifications perdues

Symptômes : - Texte corrigé disparaît après rechargement - Retour à la description originale

Solutions :

  1. Vérifiez l'indicateur de sauvegarde :

  2. Attendez "✅ Sauvegardé" avant de changer d'épisode

  3. Testez avec un petit texte :

  4. Faites une modification mineure

  5. Vérifiez qu'elle se sauvegarde correctement

  6. Contrôlez l'ID d'épisode :

  7. Vérifiez que l'URL contient le bon ID d'épisode

🎯 Problèmes de sélection d'épisodes

Liste d'épisodes vide

Symptômes : - Menu déroulant vide ou avec message d'erreur - "Aucun épisode disponible"

Solutions :

  1. Vérifiez la base de données MongoDB : 

    # Connectez-vous à MongoDB
mongosh
use lmelp
db.episodes.countDocuments()

  2. Contrôlez les logs backend :

  3. Messages d'erreur de connexion MongoDB

  4. Erreurs de requêtes

  5. Redémarrez les services : 

    # Backend (sélection automatique de port)
Ctrl+C puis python -m back_office_lmelp.app

# Frontend
Ctrl+C puis npm run dev

Épisode ne se charge pas après sélection

Symptômes : - Clic sur épisode sans effet - Zone de détails reste vide

Solutions :

  1. Vérifiez l'ID d'épisode :
  2. Console navigateur (F12) → erreurs JavaScript

  3. Recherchez les erreurs d'ObjectId MongoDB

  4. Testez un autre épisode :

  5. Vérifiez si le problème est général ou spécifique

  6. Rechargez complètement :

  7. Ctrl+Shift+R (rechargement force)

🧠 Problèmes de mémoire

Application se ferme brutalement

Symptômes : - Page se recharge automatiquement - Message "Limite mémoire dépassée" - Onglet se ferme tout seul

Explication : Les garde-fous mémoire protègent le système en rechargeant/fermant l'application si elle consomme trop de mémoire.

Solutions :

  1. Réduisez les onglets ouverts :
  2. Fermez les onglets inutiles

  3. Libérez de la mémoire RAM

  4. Redémarrez le navigateur :

  5. Complètement fermer et rouvrir le navigateur

  6. Vide le cache mémoire

  7. Travaillez sur des épisodes plus courts :

  8. Évitez les très longues transcriptions
  9. Divisez le travail en sessions courtes

Alertes mémoire fréquentes

Symptômes : - Messages "⚠️ Attention: utilisation mémoire élevée" - Performance dégradée

Solutions :

  1. Surveillance préventive :
  2. Sauvegardez plus fréquemment

  3. Rechargez périodiquement la page

  4. Optimisation navigateur :

  5. Fermez les extensions non nécessaires
  6. Utilisez un navigateur avec moins d'onglets

🖥️ Problèmes d'interface

Interface déformée ou mal affichée

Symptômes : - Éléments qui se chevauchent - Texte coupé ou illisible - Boutons non cliquables

Solutions :

  1. Vérifiez le zoom du navigateur :
  2. Ctrl+0 pour remettre à 100%

  3. Ou ajustez avec Ctrl++ / Ctrl+-

  4. Testez un autre navigateur :

  5. Chrome, Firefox, Safari, Edge

  6. Vérifiez la compatibilité

  7. Videz le cache :

  8. Ctrl+Shift+R
  9. Ou effacez le cache dans les paramètres

Zone de texte non éditable

Symptômes : - Impossible de cliquer dans "Description corrigée" - Curseur ne s'affiche pas - Saisie au clavier sans effet

Solutions :

  1. Vérifiez la sélection d'épisode :

  2. Un épisode doit être sélectionné pour éditer

  3. Rechargez la page :

  4. F5 pour rafraîchir l'interface

  5. Testez avec un autre épisode :

  6. Le problème peut être spécifique à un épisode

📱 Problèmes mobile/responsive

Interface difficile à utiliser sur mobile

Solutions :

  1. Orientation paysage :
  2. Tournez l'appareil en mode paysage

  3. Plus d'espace pour l'édition

  4. Zoom adaptatif :

  5. Pincez pour zoomer sur les zones d'édition

  6. Dézoomez pour voir l'ensemble

  7. Navigateur moderne :

  8. Utilisez Chrome ou Firefox mobile
  9. Évitez les navigateurs intégrés d'applications

Diagnostics avancés

Console du navigateur (F12)

Onglet Console

Recherchez ces types d'erreurs :

// Erreurs réseau
Failed to fetch
Network Error

// Erreurs JavaScript
TypeError: Cannot read properties
ReferenceError: variable is not defined

// Erreurs API
404 Not Found
500 Internal Server Error

Onglet Network

Vérifiez les requêtes HTTP :

// Requêtes qui échouent
GET /api/episodes → Status: 500 (Rouge)
PUT /api/episodes/123 → Status: 404 (Rouge)

// Requêtes normales
GET /api/episodes → Status: 200 (Vert)
PUT /api/episodes/123 → Status: 200 (Vert)

Onglet Application

Vérifiez le stockage local :

  • localStorage peut contenir des données corrompues
  • Effacez si nécessaire : Application > Storage > Clear

Tests manuels

Test API directe

  1. Consultez le terminal backend pour connaître le port utilisé
  2. Ouvrez : http://localhost:[PORT]/docs (remplacez [PORT] par le port affiché)
  3. Testez GET /api/episodes
  4. Testez GET /api/episodes/{id}
  5. Testez PUT /api/episodes/{id}

Test de connectivité

# Test ping du backend (consultez le terminal pour connaître le port)
curl http://localhost:[PORT]/api/episodes

# Test avec timeout
curl --max-time 5 http://localhost:[PORT]/api/episodes

Logs détaillés

Backend (Python)

Ajoutez plus de logs si nécessaire :

import logging
logging.basicConfig(level=logging.DEBUG)

Frontend (JavaScript)

Activez les logs détaillés dans la console :

// Dans la console navigateur
localStorage.debug = '*'
// Puis rechargez la page

Problèmes connus et workarounds

1. Port 54321 occupé (Issue #1 - RÉSOLU)

Problème précédent : Le port 54321 restait occupé après arrêt du serveur FastAPI Cause identifiée : Arrêt non gracieux du serveur (utilisation d'os._exit() et signaux mal gérés) Résolution appliquée : - Amélioration de la gestion des signaux SIGINT/SIGTERM - Remplacement d'os._exit() par SystemExit pour permettre un cleanup propre - Ajout de timeouts configurables pour l'arrêt gracieux d'uvicorn - Tests ajoutés pour vérifier l'arrêt propre du serveur Status : ✅ Complètement résolu

3. Sélection manuelle de port (Issue #13 - RÉSOLU)

Problème précédent : Utilisateurs devaient manuellement spécifier un port libre lors du démarrage Impact précédent : Échec de démarrage si le port par défaut était occupé Résolution appliquée : - Sélection automatique de port avec stratégie de priorité - Port préféré 54321, fallback 54322-54350, attribution OS en dernier recours - Variable d'environnement API_PORT conservée pour override manuel - Message clair indiquant quand le port est sélectionné automatiquement - 7 nouveaux tests couvrant tous les scénarios de sélection Status : ✅ Complètement résolu depuis Issue #13

2. Configuration ports statique (Issue #2 - RÉSOLU)

Problème précédent : Port hardcodé dans la configuration frontend créant des désynchronisations Impact précédent : Nécessitait modification manuelle en cas de changement de port backend Résolution appliquée : -- Système de découverte automatique de port via fichier .dev-ports.json - Frontend lit automatiquement les informations de port du backend - Fallback intelligent vers port par défaut si fichier manquant ou obsolète - Tests complets pour garantir la robustesse (13 nouveaux tests) Status : ✅ Complètement résolu

3. Tests frontend activés (Issue #7 - RÉSOLU)

Problème précédent : 26 tests frontend ignorés dans CI/CD Résolution : Tests intégrés dans le pipeline (63 tests total : 32 backend + 31 frontend) Status : ✅ Complètement résolu depuis septembre 2025

Escalation et support

Informations à collecter

En cas de problème persistant, rassemblez :

  1. Environnement :
  2. Système d'exploitation
  3. Version du navigateur

  4. Version de l'application

  5. Logs :

  6. Messages d'erreur console (F12)
  7. Logs du terminal backend

  8. Logs MongoDB si pertinents

  9. Reproduction :

  10. Étapes pour reproduire le problème
  11. Fréquence du problème
  12. Épisodes affectés

Ressources d'aide

Solutions de contournement temporaires

  1. Travail hors ligne :
  2. Copiez le texte dans un éditeur externe

  3. Collez-le ensuite quand l'app fonctionne

  4. Sauvegarde manuelle :

  5. Copiez régulièrement votre travail

  6. Utilisez Ctrl+S fréquemment

  7. Sessions courtes :

  8. Travaillez par petites sessions
  9. Rechargez périodiquement pour éviter les fuites mémoire

Cette documentation de résolution de problèmes évolue en fonction des retours utilisateurs. N'hésitez pas à signaler de nouveaux problèmes pour améliorer cette ressource.