4NK_IA_front/docs/systeme-pending.md

Système de Pending et Polling

Vue d'ensemble

Le système de pending permet de gérer les fichiers en cours de traitement de manière robuste, avec un système de flags et de polling automatique pour mettre à jour l'interface utilisateur en temps réel.

Architecture

Backend (Node.js)

Fonctions principales

• createPendingFlag(folderHash, fileHash) : Crée un flag .pending avec métadonnées
• isFilePending(folderHash, fileHash) : Vérifie si un fichier est en cours de traitement
• cleanupOrphanedPendingFlags() : Nettoie les flags orphelins (> 1 heure)

Gestion des flags

// Structure d'un flag pending
{
  fileHash: "abc123...",
  folderHash: "def456...",
  timestamp: "2025-09-16T02:58:29.606Z",
  status: "processing"
}

API Endpoints

• GET /api/folders/:folderHash/results : Retourne les résultats + informations pending
• POST /api/extract : Crée un flag pending avant traitement, retourne HTTP 202 si déjà en cours

Gestion d'erreur

• Suppression automatique des flags pending en cas d'erreur
• Gestion try/catch/finally pour garantir le nettoyage
• Nettoyage des flags orphelins au démarrage du serveur

Frontend (React + Redux)

État Redux

interface DocumentState {
  // ... autres propriétés
  pendingFiles: Array<{
    fileHash: string
    folderHash: string
    timestamp: string
    status: string
  }>
  hasPending: boolean
  pollingInterval: NodeJS.Timeout | null
}

Actions Redux

• setPendingFiles : Met à jour la liste des fichiers pending
• setPollingInterval : Gère l'intervalle de polling
• stopPolling : Arrête le polling et nettoie l'intervalle

Polling automatique

• Démarrage automatique si hasPending = true
• Polling toutes les 5 secondes
• Arrêt automatique quand plus de pending
• Nettoyage des intervalles au démontage des composants

Flux de fonctionnement

1. Upload d'un fichier

sequenceDiagram
    participant F as Frontend
    participant B as Backend
    participant FS as FileSystem

    F->>B: POST /api/extract (file + folderHash)
    B->>B: Calculer fileHash
    B->>B: Vérifier cache
    B->>B: Vérifier pending
    B->>FS: Créer flag .pending
    B->>B: Traitement OCR/NER
    B->>FS: Sauvegarder résultat .json
    B->>FS: Supprimer flag .pending
    B->>F: Retourner résultat

2. Polling automatique

sequenceDiagram
    participant F as Frontend
    participant B as Backend

    F->>B: GET /api/folders/:hash/results
    B->>F: { results: [], pending: [], hasPending: true }
    F->>F: Démarrer polling (5s)

    loop Polling
        F->>B: GET /api/folders/:hash/results
        B->>F: { results: [1], pending: [], hasPending: false }
        F->>F: Arrêter polling
    end

3. Gestion d'erreur

sequenceDiagram
    participant B as Backend
    participant FS as FileSystem

    B->>FS: Créer flag .pending
    B->>B: Traitement (ERREUR)
    B->>FS: Supprimer flag .pending
    B->>B: Retourner erreur 500

Configuration

Variables d'environnement

• Polling interval : 5000ms (5 secondes)
• Cleanup threshold : 1 heure pour les flags orphelins

Structure des dossiers

uploads/
├── {folderHash}/
│   ├── {fileHash}.pdf
│   └── {fileHash}.jpg
cache/
├── {folderHash}/
│   ├── {fileHash}.json
│   └── {fileHash}.pending (temporaire)

Avantages

1. Robustesse : Gestion des erreurs et nettoyage automatique
2. Performance : Évite les traitements en double
3. UX : Mise à jour automatique de l'interface
4. Maintenance : Nettoyage automatique des flags orphelins

Tests

Tests manuels

1. Upload simple : Vérifier création/suppression du flag
2. Upload en double : Vérifier retour HTTP 202
3. Erreur de traitement : Vérifier suppression du flag
4. Polling : Vérifier mise à jour automatique
5. Nettoyage : Redémarrer serveur, vérifier nettoyage des orphelins

Commandes de test

# Vérifier l'état d'un dossier
curl -s http://localhost:3001/api/folders/{hash}/results | jq '.count, .hasPending'

# Tester l'upload
curl -X POST -F "document=@test.pdf" -F "folderHash={hash}" http://localhost:3001/api/extract

Maintenance

Nettoyage manuel

# Supprimer tous les flags pending (attention !)
find cache/ -name "*.pending" -delete

# Vérifier les flags orphelins
find cache/ -name "*.pending" -mtime +0

Monitoring

• Logs de création/suppression des flags
• Logs de polling dans la console frontend
• Métriques de temps de traitement