187 lines
4.6 KiB
Markdown
187 lines
4.6 KiB
Markdown
# 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
|