4NK_IA_front/docs/CACHE_ET_TRAITEMENT_ASYNC.md

Cache des résultats et traitement asynchrone

Dossiers utilisés

• uploads/<folderHash>: fichiers déposés (source de vérité)
• cache/<folderHash>: résultats JSON et flags .pending (source pour l’API)
• backend/cache/*: (désormais vide) ancien emplacement – ne plus utiliser

Flux de traitement

1. Dépôt d’un fichier (/api/extract):

   • Calcule fileHash (SHA‑256 du contenu)
   • Si cache/<folderHash>/<fileHash>.json existe: renvoie immédiatement le JSON
   • Sinon: crée cache/<folderHash>/<fileHash>.pending, lance l’OCR/NER, puis écrit le JSON et supprime .pending

2. Listing (/api/folders/:folderHash/results):

   • Agrège tous les JSON présents dans cache/<folderHash>/
   • Pour chaque fichier présent dans uploads/<folderHash> sans JSON, crée un flag .pending et lance le traitement en arrière‑plan, sans bloquer la réponse

Points importants

• Le traitement images/PDF peut être long; le listing n’attend pas la fin
• Le frontal réalise un polling périodique si hasPending=true
• Les erreurs de traitement suppriment le flag .pending et la requête renvoie 500 (extraction) ou 200 avec moins de résultats (listing)

Bonnes pratiques

• N’écrire les résultats que dans cache/<folderHash> à la racine
• Toujours indexer les résultats par fileHash.json
• Protéger les accès à .length et valeurs potentiellement undefined dans le backend