# ThePepite — architecture, phase 0 Phase 0 validée le 10 novembre 2026. Le volet carburant local est implémenté ; les sections ci-dessous décrivent aussi les composants futurs. ## Arborescence et responsabilités ``` collector/ Python 3.11+ : adaptateurs autorisés, normalisation, reprise et dédoublonnage scoring/ pandas, scikit-learn, LightGBM CPU ; références et règles explicables api/ FastAPI : lecture publique, estimation et soumissions limitées web/ Cible produit : Next.js App Router + Tailwind extension/ Chrome/Firefox Manifest V3, builds distincts et tests de compatibilité bot/ Publication Telegram depuis une file transactionnelle db/ PostgreSQL : migration initiale et tests d'intégrité dist/ Présentation statique de phase 0, publiée sur Sites ``` La présentation statique permet de tester Sites sans lancer la phase 1. Ce n'est pas encore l'application Next.js. Le futur front devra utiliser un export statique Next.js compatible avec Sites ou faire valider une adaptation de runtime. Python/FastAPI/PostgreSQL ne sont pas exécutables tels quels dans le runtime Cloudflare Workers de Sites. ## Flux prévu Sources autorisées → collecte locale planifiée → validation et suppression des données personnelles → offres et observations PostgreSQL → scoring → filtres de publication → API → site et file Telegram. Les tâches s'exécutent sous cron Linux/WSL ; sous Windows natif, le Planificateur de tâches remplace cron. Verrou par source pour éviter les doubles exécutions, timeouts, Retry-After, reprise avec temporisation et contrôle des erreurs. Machine éteinte = collecte et alertes arrêtées. « Temps réel » signifie après détection, pas à la seconde près. ## Hébergement - Développement : PostgreSQL dans Docker, Python et Next.js locaux aux phases suivantes. - Prototype actuel : fichiers statiques sur Sites, accès privé au propriétaire. - Production proposée : front Sites ; API et PostgreSQL sur une machine accessible en HTTPS, ou API sur hébergement séparé et PostgreSQL Supabase. Ne jamais exposer PostgreSQL sur Internet. - L'API locale ne sera pas accessible depuis un site public sans hébergement ou accès HTTPS adapté. Ce choix reste à valider avant la phase 1. - Next.js/Vercel gratuit est incompatible avec la monétisation envisagée selon les règles Hobby ; voir SOURCES.md. Aucun abonnement ni source payante souscrits. ## Contrats et sécurité GET /v1/offers : catégorie, tri, pagination, fraîcheur ; lecture de public_offers uniquement. GET /v1/offers/{id} : référence, période, échantillon et raisons du score. POST /v1/estimates (phase 2) : attributs validés, calcul éphémère sans sauvegarde par défaut. POST /v1/submissions (phase 2) : partage explicite, limite de taille, modération, aucune publication directe. La modération reste locale et protégée ; absence de comptes visiteurs ne signifie pas administration anonyme. Rôles PostgreSQL séparés à provisionner en phase 1 : migrations, collecte, API lecture, API soumissions. CORS limité aux origines autorisées ; les identifiants secrets ne vont jamais dans le navigateur. Les URL soumises ne sont jamais téléchargées automatiquement : liste de domaines admis, retrait des paramètres personnels, refus des IP locales et schémas autres que HTTPS. Le lien d'affiliation officiel doit rester intact quand ses conditions l'exigent. ## Données et confidentialité offer_key = identifiant stable dans une source ; product_key = rapprochement du même produit, variante, état, région et unité. Les prix sont décimaux, pas des flottants. L'historique reste dans la devise d'origine ; jamais de comparaison EUR/USD sans conversion documentée. Liste blanche d'attributs par catégorie, champs scalaires bornés. Pas de HTML, description libre, nom de vendeur, téléphone, email, pseudo, plaque, VIN ou adresse de particulier. Titres reconstruits à partir des attributs. Aucun payload brut conservé. Les contraintes JSON SQL sont une défense complémentaire, pas un système de détection de données personnelles. Nettoyage obligatoire avant base, logs et sauvegardes. Durées proposées : soumissions rejetées 30 jours, logs techniques expurgés 30 jours, offres expirées 90 jours avant archivage minimal, historique non personnel 24 mois. Procédure de retrait et purge des sauvegardes à implémenter. Aucun suivi publicitaire dans le prototype. ## Référence et scoring score_pepite = (prix_reference - prix) / prix_reference ; référence nulle, nulle au sens SQL ou insuffisante = aucun score publié. Une forte remise ne prouve pas la fiabilité. E-commerce/jeux : médiane historique propre, comparables disponibles, frais inclus et fenêtre documentée. Démarrage sans historique = état « données insuffisantes », pas de faux prix de marché. Carburant : médiane contemporaine de stations comparables dans une zone, même carburant, €/litre, prix récents et ruptures exclues. Les seuils initiaux du SQL sont des hypothèses désactivées. Auto : LightGBM CPU seulement après volume suffisant, validation temporelle et dédoublonnage par véhicule, MAE/MAPE par segment, intervalle d'incertitude. Aucun historique vendeur conservé. Enchères : inclure frais, TVA, enlèvement ; une mise à prix n'est pas un prix d'acquisition garanti. Immobilier : agrégats DVF, types comparables, traitement prudent des ventes multi-lots, seuil d'échantillon et pas de transactions brutes indexables. Indice de fiabilité de 0 à 100 : règles explicables, valeurs manquantes distinctes d'une preuve de fraude. Afficher « vigilance » plutôt qu'une accusation non vérifiée. Aucun LLM requis au départ. ## Exploitation et tests prévus Une transaction écrit l'offre, son observation et l'événement d'alerte. Une clé événement empêche les doublons internes. Telegram n'offre pas une garantie générale d'envoi exactement une fois : en cas de timeout après envoi, statut unknown et contrôle avant réessai. Phase 1 : fixtures autorisées pour collecteurs, tests de prix zéro/devise/fraîcheur/ruptures, idempotence, filtrage des sources interdites, absence de données personnelles et tests de seuils. Aucun collecteur ou modèle implémenté en phase 0. Checkpoint 1 : sept jours observés avec journal de disponibilité, erreurs et revue manuelle des offres ; ne pas déclarer ce test réalisé à l'installation. ## Recherche globale Le prototype propose une recherche par mots-clés sur les six catégories, le contenu de la page et les documents de cadrage. Accents et casse sont ignorés ; tous les mots saisis doivent correspondre. Les résultats privilégient les titres. Aucune requête n'est conservée ou transmise à un tiers. Les exemples fictifs ne sont pas des offres réelles. Phase 1 : prévoir GET /v1/search?q=... avec PostgreSQL full-text et index GIN, normalisation des accents, pagination et filtres catégorie/prix. Interroger uniquement les offres publiables et fraîches, ainsi que les pages éditoriales. La recherche doit être présente dans l'en-tête de chaque page Next.js, sur mobile comme sur ordinateur. Ne pas exposer les soumissions, données internes ou offres retirées. ## État du volet carburant au 10 novembre 2026 PostgreSQL 16, collecteur Python, médiane BallTree/pandas et FastAPI actifs en local. Planificateur Windows toutes les 30 minutes, à la place de cron sur cet hôte Windows. Site local servi par FastAPI ; Sites reçoit un export statique horodaté à chaque publication manuelle. Aucune liaison automatique de Sites au PC. Interface toujours statique : Next.js reste une étape distincte. Telegram sans configuration reste désactivé. Voir README.md pour les tests, commandes et limites actuelles.