# Cycle de vie d'une analyse

> Les statuts d'un scan antivirus, leurs transitions, les nouvelles tentatives automatiques et le moment où un crédit est consommé.

Une analyse antivirus est un traitement asynchrone : l'API vous répond avant que ClamAV ait examiné le fichier. Le statut du scan vous dit où en est le traitement, et seul un statut final vous autorise à décider du sort du fichier.

## Définition

Un **scan** est l'enregistrement que Wakastart crée à chaque fichier envoyé à `POST /api/antivirus/scans`. Il porte un identifiant UUID, le nom et la taille du fichier, son statut et, une fois l'analyse finie, le verdict.

Un scan appartient au [client](/v1.0/glossaire#client) et à l'application de l'appelant. Tout utilisateur ou toute clé du même client disposant du droit **Voir le module antivirus** peut le consulter.

```mermaid
stateDiagram-v2
  [*] --> PENDING: POST /api/antivirus/scans
  PENDING --> SCANNING: prise en charge par la file
  SCANNING --> CLEAN: aucune menace
  SCANNING --> INFECTED: menace détectée
  SCANNING --> ERROR: incident technique
  ERROR --> SCANNING: nouvelle tentative (3 au total)
  CLEAN --> [*]
  INFECTED --> [*]
  ERROR --> [*]: après la 3e tentative
```

## Pourquoi c'est asynchrone

Analyser un fichier prend de quelques centaines de millisecondes à plusieurs secondes selon sa taille et sa structure (une archive est examinée fichier par fichier). Répondre tout de suite évite de bloquer la requête de votre serveur, et donc celle de votre utilisateur, pendant l'analyse. Une file d'attente absorbe aussi les pics d'envoi.

## Comment ça marche

### Les statuts

| Statut | Signification | Final |
|---|---|---|
| `PENDING` | Le fichier est reçu et attend son tour dans la file. | Non |
| `SCANNING` | ClamAV examine le fichier. | Non |
| `CLEAN` | Aucune menace détectée. Vous pouvez accepter le fichier. | Oui |
| `INFECTED` | Une menace est détectée. Le fichier est en quarantaine ; `threatName` donne son nom. | Oui |
| `ERROR` | L'analyse a échoué pour une raison technique. `errorMessage` en donne la cause. | Après trois tentatives |

### Les nouvelles tentatives

Un incident technique (moteur momentanément injoignable, délai de 30 secondes dépassé) fait passer le scan en `ERROR`. Wakastart relance alors l'analyse automatiquement, jusqu'à trois tentatives au total, avec un délai croissant entre elles (5 s, puis 10 s). Entre deux tentatives, vous pouvez donc voir `ERROR` puis de nouveau `SCANNING`.

Un scan resté en `ERROR` après la troisième tentative est définitif. Il ne déclenche pas de webhook : seule l'interrogation de l'API vous le signale.

### La file d'attente et la priorité

Chaque scan porte une priorité de 1 à 10, 5 par défaut. **1 est la priorité la plus haute** : un scan de priorité 1 passe devant ceux de priorité 5. Trois analyses tournent en parallèle ; les autres attendent leur tour.

### Le cache d'empreinte

Wakastart calcule l'empreinte SHA-256 de chaque fichier. Si un fichier de même empreinte a déjà été déclaré `INFECTED` pour le même client et la même application, le nouveau scan est déclaré `INFECTED` sans repasser par le moteur. Le champ `threatName` reprend alors le nom de la menace connue.

### La consommation de crédits

Chaque envoi consomme **1 crédit**, débité sur le solde du client à la réception de la demande, avant l'analyse. Le crédit est consommé quel que soit le verdict : `CLEAN`, `INFECTED` ou `ERROR`. Sans crédit disponible, l'API refuse l'envoi avec une erreur `402`.

## Exemples

- **Une plateforme de recrutement** reçoit des CV. Son serveur envoie chaque CV avec un webhook, enregistre le fichier comme « en cours de vérification », puis le rend visible aux recruteurs à la réception du verdict `CLEAN`.
- **Un import nocturne** de 2 000 pièces jointes envoie les fichiers en priorité 8, pour laisser passer devant lui les téléversements des utilisateurs connectés, envoyés en priorité 5.
- **Un justificatif d'identité** attendu en direct par un conseiller est envoyé en priorité 1.

## Pour aller plus loin

- [Quarantaine et politique d'analyse](/v1.0/antivirus/quarantaine-et-politique)
- [Suivre une analyse par interrogation](/v1.0/antivirus/suivre-une-analyse)
- [Recevoir le résultat par webhook](/v1.0/antivirus/recevoir-le-resultat-par-webhook)
- [Référence : objet scan et statuts](/v1.0/antivirus/reference)
