# 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

```javascript
// 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

```typescript
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

```mermaid
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

```mermaid
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

```mermaid
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

```bash
# 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

```bash
# 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