# ThePepite — phase 1, premier volet carburant

La phase 0 a été validée. Le collecteur carburant, le scoring géographique, PostgreSQL et FastAPI fonctionnent sur le PC. Le site conserve son prototype statique validé ; la migration du front vers Next.js reste à réaliser avant de considérer la stack initialement demandée comme entièrement livrée.

## Accès
- Site local : http://127.0.0.1:8000/carburant.html — données de PostgreSQL, page rafraîchie toutes les 60 secondes.
- Documentation API locale : http://127.0.0.1:8000/docs
- Sites : https://thepepite-atelier.exactcanopy.chatgpt.site/carburant.html — instantané au moment de la publication, pas de liaison directe à votre PC.
- La collecte est planifiée toutes les 30 minutes par la tâche Windows `ThePepite-Carburant`, seulement quand votre session est ouverte et Docker fonctionne. PC éteint/en veille = collecte interrompue. La tâche ne réveille pas le PC et ne publie pas automatiquement sur Sites.
- Les prix expirent à 72 heures après leur mise à jour officielle, ou 2 heures après la dernière vérification réussie. Sur Sites, l'instantané devient donc rapidement vide : c'est volontaire, pour ne pas présenter de vieux prix comme frais.

## Résultat initial et vérifications
Première collecte le 10 novembre 2026 : 18 516 prix enregistrés, 674 résultats éligibles aux seuils provisoires. Ces nombres ne sont pas une mesure de pertinence et varient à chaque collecte.
Tests unitaires du parseur, du scoring et de l'API ; contraintes SQL exécutées sur PostgreSQL ; plusieurs collectes réelles, vérification de l'absence de doublons journaliers. Contrôle visuel de cette nouvelle version non effectué : le contrôle du navigateur local est désactivé dans les réglages de l'application.
Telegram n'est pas configuré et aucun message n'a été envoyé. Le code et la file d'attente sont prêts, mais l'envoi réel n'est pas validé.

## Installation et lancement
Prérequis : Docker Desktop avec moteur Linux en marche, PowerShell, ports locaux 5433 et 8000 disponibles. Les ports sont limités à 127.0.0.1 ; aucune base de données n'est exposée sur Internet.
Dans ce dossier :
```powershell
# Seulement pour une installation neuve :
Copy-Item .env.example .env
# Modifier POSTGRES_PASSWORD dans .env. Ne pas remplacer le .env existant.
powershell.exe -NoProfile -File scripts/start.ps1
powershell.exe -NoProfile -File scripts/collect.ps1
# Seulement si la tâche n'existe pas encore :
powershell.exe -NoProfile -File scripts/install-schedule.ps1
```
Le schéma 001 s'applique uniquement à un volume vide ; 002 est idempotent. Ne jamais supprimer le volume pour appliquer une migration. Les versions Python résolues sont dans requirements.lock.txt et utilisées lors de la construction.

## Fonctionnement et critères
Source exclusive : flux officiel instantane_ruptures, licence ouverte, attribution dans l'interface. Aucune page de petites annonces téléchargée. Coordonnées converties depuis les unités officielles ; prix en euros, sans division par mille. Station identifiée par son ID : le flux ne fournit ni enseigne ni nom commercial.
Comparaison avec les AUTRES stations, même carburant et même type route/autoroute, rayon géographique de 20 km. Minimum 5 stations ; médiane contemporaine. Publication avec écart ≥ 5 % et indice de cohérence ≥ 80/100. Un écart absolu supérieur à 30 % est exclu du circuit de publication. L'indice n'est pas une certification anti-arnaque et n'est pas présenté comme tel.
Seuils et nombre minimum : table category_policies. Le rayon de 20 km et la fraîcheur de 72 h sont pour le moment des paramètres de code. L'API et l'export masquent les offres non éligibles, retirées ou non vérifiées depuis deux heures.
Un seul relevé par offre et jour UTC ; la valeur est mise à jour au dernier passage de la journée. Pas d'historique complet intrajournalier. La référence carburant est une médiane locale, pas une médiane historique de prix.
L'export fuel-snapshot.json est atomique. Les anciennes données expirent dans l'interface si une collecte échoue. Les journaux contiennent les compteurs et codes d'erreur, sans contenu brut du flux ni secrets.

## Tests et contrôle
```powershell
docker compose --profile jobs run --rm collector python -m pytest -q
Get-Content db/test_integrity.sql -Raw | docker compose exec -T db psql -v ON_ERROR_STOP=1 -U thepepite -d thepepite
Get-ScheduledTaskInfo -TaskName ThePepite-Carburant
Get-Content runtime/collect-*.log -Tail 20
```
Le dernier résultat de tâche doit être 0 après exécution. Les paramètres sont limités à une installation locale : l'API utilise encore le rôle de développement PostgreSQL. Avant exposition publique, provisionner les rôles minimaux, HTTPS, supervision et limites d'accès.

## Telegram : configuration locale uniquement
Créer le bot et le canal dans votre compte Telegram, donner au bot le droit de publier, puis renseigner TELEGRAM_BOT_TOKEN et TELEGRAM_CHANNEL_CARBURANT dans .env. Ne pas transmettre le jeton dans le chat. Le job charge .env à chaque exécution. Le bot n'envoie que les nouveaux événements récents encore publiables, au maximum 10 par passage ; aucun backlog de plus de deux heures. Timeout ambigu => unknown, sans retry automatique ; contrôler dans Telegram avant toute reprise manuelle.
L'envoi se fait ensuite à la fin de la collecte planifiée. Aucun code promo, source payante ou réseau d'affiliation n'est activé.

## Arrêter / reprendre
```powershell
Disable-ScheduledTask -TaskName ThePepite-Carburant
docker compose stop
# Reprise : démarrer Docker, puis
docker compose up -d db api
Enable-ScheduledTask -TaskName ThePepite-Carburant
```
Pour un export de sauvegarde, utiliser pg_dump localement ; ne pas publier le fichier .env, les volumes ou les sauvegardes. Le volume PostgreSQL est conservé lors d'un arrêt normal.

## Checkpoint 1 : non atteint
Il reste sept jours réels d'observation et une revue de pertinence des résultats ; aucune validation automatique n'est déclarée. Suivre les échecs dans collection_runs, les intervalles sans collecte, les stations en rupture et un échantillon d'écarts. Le temps où le PC est éteint ne constitue pas du fonctionnement continu.
Restent également : configuration et test réel de Telegram, droits d'accès aux sources jeux/affiliation, choix d'un backend accessible en HTTPS pour un service public actualisé, front Next.js et règles de rétention automatisées. La phase 2 automobile n'est pas engagée.