docs/API.md

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 (Netlify) et l'API (Hugging Face Spaces) sont sur des domaines différents. Par défaut "*" (permissif, adapté à une démo) ; à restreindre au domaine Netlify 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).

POST /feedback

Correction a posteriori d'une transaction déjà traitée par /analyze — voir docs/MONITORING.md pour le fonctionnement complet de la boucle d'apprentissage continu.

Champ	Type	Requis	Description
photo_reference	string	oui	valeur renvoyée par /analyze (doit exister dans photos/)
corrected_prix	float	non*	montant réellement correct
corrected_volume	float	non*	volume réellement correct
corrected_prix_litre	float	non*	prix du litre réellement correct
corrected_by	string	non	identifiant de qui corrige (pompiste/station)

* au moins un des trois champs corrected_* est requis.

Réponses : 200 ({"success": true, "feedback_id": "..."}), 404 si photo_reference ne correspond à aucune photo connue, 400 si aucune correction n'est fournie.

GET /metrics

Aperçu agrégé des performances observées en production, calculé à la volée à partir de logs/api.log (pas de paramètre, pas d'état en mémoire) : total_requests, success_rate, avg_confidence_score, blocking_causes, image_quality_distribution. Voir docs/MONITORING.md.

GET /failures

Les limit (défaut 20) dernières transactions bloquées (success=false), les plus récentes en premier — alimente la section « Requêtes échouées » de web/stats.html. Chaque élément : photo_reference, message, image_quality, detected_liters, detected_amount, fuel_price, confidence_score, transaction_datetime.

GET /photos/{photo_reference}

Ressert l'image sauvegardée par /analyze sous ce photo_reference (sert l'affichage dans le tableau de bord et le formulaire de correction). 404 si la référence est inconnue. photo_reference est assaini côté serveur (Path(...).name) avant résolution sous PHOTOS_DIR — aucune traversée de répertoire possible même si la valeur contient ../.