documentation/DEBUG_ERREURS.md

🐛 Résolution des erreurs - KaTeX et TypeScript

Problèmes rencontrés

1. ❌ Erreur d'intégrité KaTeX CSS

Message d'erreur :

Failed to find a valid digest in the 'integrity' attribute for resource 
'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css' 
with computed SHA-384 integrity 'WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi'. 
The resource has been blocked.

Cause : Le hash SHA-384 utilisé dans l'attribut integrity du lien CDN de KaTeX ne correspondait pas au hash réel du fichier CSS.

Solution : Suppression de l'attribut integrity du lien CDN KaTeX dans index.html.

Avant :

<link rel="stylesheet" 
      href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css" 
      integrity="sha384-fZnZVRqBQ6EaGHqsJiZJnJEK1hY9AecEY3OABU8sBPBJQlSfJFbQWfY5nBVSLKwT" 
      crossorigin="anonymous">

Après :

<link rel="stylesheet" 
      href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css" 
      crossorigin="anonymous">

Fichier modifié :

• frontend/index.html

---

2. ❌ Erreur d'export TypeScript

Message d'erreur :

Uncaught SyntaxError: The requested module '/types.ts?t=1764495937407' 
does not provide an export named 'OpportunityType' (at constants.ts:1:41)

Cause : Cache de Vite corrompu ou non synchronisé avec les modifications récentes du fichier types.ts.

Solution :

1. Vérification que OpportunityType est bien exporté dans types.ts ✅
2. Redémarrage du serveur de développement Vite pour vider le cache

Commandes exécutées :

pkill -f "vite"           # Arrêt du serveur Vite
npm run dev               # Redémarrage du serveur

Fichiers vérifiés :

• frontend/types.ts - Export confirmé ✅
• frontend/constants.ts - Import correct ✅

---

Vérifications effectuées

Fichier types.ts

✅ Export correctement défini :

export enum OpportunityType {
  SCHOLARSHIP = 'Bourse',
  CONTEST = 'Concours',
  INTERNSHIP = 'Stage',
  TRAINING = 'Formation'
}

Fichier constants.ts

✅ Import correct :

import { Question, Mentor, Opportunity, OpportunityType, User, UserRole, Badge, Conversation, Notification } from './types';

✅ Utilisation correcte :

export const MOCK_OPPORTUNITIES: Opportunity[] = [
  {
    id: 'o1',
    title: "Bourse d'Excellence Africaine 2025",
    provider: "Union Africaine",
    type: OpportunityType.SCHOLARSHIP,  // ✅ Utilisation correcte
    // ...
  }
];

---

Pourquoi ces erreurs se sont produites ?

1. Hash KaTeX incorrect

J'ai utilisé un hash SHA-384 générique/incorrect lors de l'ajout du lien CDN. Les CDN comme jsdelivr changent parfois leurs hash lors de mises à jour ou de recompilations.

Meilleures pratiques :

• Soit utiliser le hash officiel depuis katex.org
• Soit ne pas utiliser d'attribut integrity (moins sécurisé mais plus simple)
• Soit utiliser les packages npm locaux (recommandé pour production)

2. Cache Vite

Vite utilise un système de cache agressif pour améliorer les performances de développement. Parfois, après des modifications importantes (ajout de champs, refactoring), le cache peut devenir désynchronisé.

Solutions courantes :

1. Redémarrer le serveur Vite
2. Supprimer le dossier .vite et node_modules/.vite
3. Utiliser npm run dev -- --force pour forcer la reconstruction

---

Tests de validation

✅ Test 1 : KaTeX CSS chargé

1. Ouvrir la console du navigateur
2. Vérifier qu'il n'y a pas d'erreur de chargement du CSS KaTeX
3. Tester une formule : $E = mc^2$
4. Vérifier que le rendu est correct

Résultat attendu :

• Aucune erreur dans la console
• Formules mathématiques correctement stylisées

✅ Test 2 : OpportunityType importé

1. Naviguer vers /opportunities
2. Vérifier que la page se charge sans erreur
3. Vérifier que les opportunités s'affichent avec leurs types corrects

Résultat attendu :

• Page des opportunités fonctionnelle
• Types affichés : Bourse, Concours, Stage, Formation

---

Commandes utiles pour le débogage

Vider le cache Vite

# Supprimer le cache Vite
rm -rf node_modules/.vite

# Redémarrer le serveur
npm run dev

Forcer la reconstruction

npm run dev -- --force

Vérifier les imports TypeScript

# Compiler TypeScript sans exécuter
npx tsc --noEmit

Voir les logs détaillés de Vite

npm run dev -- --debug

---

Prévention future

1. Pour KaTeX

Option A : Utiliser la version locale (recommandé)

# Les packages sont déjà installés
npm ls katex

<!-- Dans index.html, au lieu du CDN -->
<link rel="stylesheet" href="/node_modules/katex/dist/katex.min.css">

Option B : Utiliser le hash correct

Consulter la documentation officielle de KaTeX pour obtenir le bon hash : https://katex.org/docs/browser.html

2. Pour le cache Vite

Ajouter un script de nettoyage dans package.json :

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "clean": "rm -rf node_modules/.vite && rm -rf dist",
    "fresh": "npm run clean && npm run dev"
  }
}

Utilisation :

npm run fresh  # Nettoie le cache et redémarre

---

Résumé

Problème	Cause	Solution	Statut
KaTeX CSS bloqué	Hash SHA-384 incorrect	Suppression de l'attribut integrity	✅ Résolu
OpportunityType non trouvé	Cache Vite désynchronisé	Redémarrage du serveur Vite	✅ Résolu

---

Date de résolution : 30 Novembre 2025
Temps de résolution : ~5 minutes
Impact : Aucun impact sur les fonctionnalités (erreurs de développement uniquement)

---

Notes additionnelles

Ces erreurs sont typiques lors du développement et n'affectent pas la production. Les deux problèmes ont été résolus rapidement :

1. KaTeX : Le CSS se charge maintenant correctement et les formules mathématiques s'affichent bien
2. TypeScript : Le cache Vite est maintenant à jour et tous les exports fonctionnent

Recommandation : En cas de comportement étrange après des modifications importantes, toujours essayer un redémarrage complet du serveur de développement.