4NK_IA_front/docs/HASH_SYSTEM.md

🔐 Système de Hash pour la Gestion des Doublons

📋 Vue d'ensemble

Le système de hash SHA-256 a été implémenté dans le backend 4NK_IA pour éviter les doublons d'upload et optimiser le stockage des fichiers. Ce système garantit qu'un fichier identique ne sera traité qu'une seule fois, même s'il est uploadé plusieurs fois.

---

🔧 Fonctionnement

1. Calcul du Hash

• Chaque fichier uploadé est analysé pour calculer son hash SHA-256
• Le hash est calculé sur le contenu binaire complet du fichier
• Utilisation de la fonction crypto.createHash('sha256') de Node.js

2. Détection des Doublons

• Avant traitement, le système vérifie si un fichier avec le même hash existe déjà
• La fonction findExistingFileByHash() parcourt le dossier uploads/
• Si un doublon est trouvé, le fichier uploadé est supprimé

3. Traitement Optimisé

• Le traitement utilise le fichier existant (pas le doublon)
• Les résultats d'extraction sont identiques pour les fichiers identiques
• Économie de ressources CPU et de stockage

---

📁 Structure des Fichiers

uploads/
├── document-1757980637671.pdf    # Fichier original
├── document-1757980640576.pdf    # Doublon (supprimé après traitement)
└── image-1757980651234.jpg       # Autre fichier unique

---

🔍 API Endpoints

GET /api/uploads

Liste tous les fichiers uploadés avec leurs métadonnées :

{
  "files": [
    {
      "name": "document-1757980637671.pdf",
      "size": 1015808,
      "hash": "a1b2c3d4e5f6789...",
      "uploadDate": "2025-09-15T23:56:14.751Z",
      "modifiedDate": "2025-09-15T23:56:14.751Z"
    }
  ],
  "count": 1,
  "totalSize": 1015808
}

---

📊 Logs et Monitoring

Logs de Hash

[HASH] Hash du fichier: a1b2c3d4e5f6789...
[HASH] Fichier déjà existant trouvé: document-1757980637671.pdf
[HASH] Nouveau fichier, traitement normal

Indicateurs de Performance

• Temps de traitement réduit pour les doublons
• Stockage optimisé (pas de fichiers redondants)
• Logs clairs pour le debugging

---

🛠️ Fonctions Techniques

calculateFileHash(buffer)

function calculateFileHash(buffer) {
  return crypto.createHash('sha256').update(buffer).digest('hex')
}

findExistingFileByHash(hash)

function findExistingFileByHash(hash) {
  const uploadDir = 'uploads/'
  if (!fs.existsSync(uploadDir)) return null

  const files = fs.readdirSync(uploadDir)
  for (const file of files) {
    const filePath = path.join(uploadDir, file)
    try {
      const fileBuffer = fs.readFileSync(filePath)
      const fileHash = calculateFileHash(fileBuffer)
      if (fileHash === hash) {
        return { path: filePath, name: file }
      }
    } catch (error) {
      console.warn(`[HASH] Erreur lors de la lecture de ${file}:`, error.message)
    }
  }
  return null
}

---

✅ Avantages

1. Économie de Stockage : Pas de fichiers dupliqués
2. Performance : Traitement plus rapide pour les doublons
3. Cohérence : Résultats identiques pour fichiers identiques
4. Monitoring : Visibilité sur les fichiers stockés
5. Sécurité : Hash SHA-256 cryptographiquement sûr

---

🔄 Workflow d'Upload

graph TD
    A[Fichier Uploadé] --> B[Calcul Hash SHA-256]
    B --> C{Hash Existe?}
    C -->|Oui| D[Supprimer Doublon]
    C -->|Non| E[Conserver Fichier]
    D --> F[Utiliser Fichier Existant]
    E --> G[Traitement Normal]
    F --> H[Extraction & NER]
    G --> H
    H --> I[Résultat JSON]

---

🧪 Tests

Test de Doublon

# Premier upload
curl -X POST -F "document=@test.pdf" http://localhost:3001/api/extract

# Deuxième upload du même fichier
curl -X POST -F "document=@test.pdf" http://localhost:3001/api/extract

Vérification

# Lister les fichiers uploadés
curl http://localhost:3001/api/uploads

---

📝 Notes d'Implémentation

• Algorithme : SHA-256 (256 bits)
• Performance : O(n) pour la recherche de doublons
• Stockage : Hash stocké en hexadécimal (64 caractères)
• Compatibilité : Fonctionne avec tous les types de fichiers supportés
• Nettoyage : Suppression automatique des doublons temporaires

---

Documentation mise à jour le 15 septembre 2025