# API (`app/main.py`)

## `POST /analyze`

### Requête (`multipart/form-data`)

| Champ | Type | Requis | Description |
|---|---|---|---|
| `image` | fichier | oui | photo du terminal de pompe (jpeg/png/bmp/webp/tiff) |
| `fuel_price` | float | non | prix du litre configuré côté YELY — fait autorité sur celui lu à l'écran |
| `driver_id` | string | non | identifiant chauffeur (issu du scan QR côté YELY) |
| `pompiste_id` | string | non | identifiant pompiste |
| `station_id` | string | non | identifiant station |

Volontairement **pas** de paramètres techniques (seuil de confiance OCR,
activer/désactiver la détection d'écran...) — contrairement au prototype
précédent, ce endpoint n'expose que les champs métier attendus par le
cahier des charges.

### Réponse (`200`)

Voir `README.md` pour un exemple complet. Tous les champs correspondent
au §13 du cahier des charges — voir `docs/POSTPROCESS_RULES.md` pour le
détail du calcul de chaque valeur, `docs/ARCHITECTURE.md` pour le
pipeline complet.

### Erreurs

| Statut | Cas |
|---|---|
| `400` | type d'image non supporté, ou fichier illisible |
| `500` | erreur interne inattendue pendant le traitement (journalisée dans `logs/api.log` avec la stack trace complète) |

## Chargement du modèle

Le CRNN est chargé **une seule fois** au premier appel (singleton
`_get_model()`), pas à chaque requête — le chargement prend 30-90s sur CPU.
Conséquence pratique : **ne pas lancer `uvicorn --reload` en usage normal**,
chaque rechargement de code redémarre le worker et donc le modèle.

## CORS

`ALLOWED_ORIGINS` (variable d'environnement, origines séparées par des
virgules) contrôle quels domaines peuvent appeler l'API depuis un
navigateur — nécessaire car le frontend (Vercel) et l'API (Hugging Face
Spaces) sont sur des domaines différents. Par défaut `"*"` (permissif,
adapté à une démo) ; à restreindre au domaine Vercel réel en production.

## Journalisation

Chaque appel écrit une ligne JSON dans `logs/api.log` : requête (sans
l'image elle-même) + réponse complète. C'est la base du suivi de
performance — voir `docs/MONITORING.md`.

## Traçabilité

Chaque photo reçue est sauvegardée dans `photos/<transaction_id>.jpg`
et référencée dans la réponse (`photo_reference`) — nécessaire pour
qu'un contrôle a posteriori (station, YELY) puisse revérifier une
transaction contestée, et c'est aussi la matière première de la boucle
d'apprentissage continu (`docs/MONITORING.md`).