Food·Ka

Les prix d'épicerie, suivis à la source

Les pastilles de la deuxième rangée sont dynamiques : elles interrogent /api/stats en direct.

Food-Ka est un agrégateur et comparateur indépendant de produits d'épicerie couvrant tout le Québec. Comparer les prix d'épicerie, c'est normalement ouvrir Metro, IGA, Maxi, Super C, Provigo, Walmart… chacun avec sa propre navigation, son panier, son format. Food-Ka retourne le problème : un connecteur dédié par bannière visite chaque site, normalise chaque produit vers un schéma unique (avec prix unitaire comparable en $/100 g) et détecte les changements de prix en continu.

Les épiceries n'offrent pas de webhooks ; Food-Ka en reproduit l'équivalent : synchronisation périodique + hash de contenu → nouveaux produits, changements de prix et retraits détectés automatiquement, chaque variation étant historisée (price_log). Au 2026-08-28, le catalogue compte 50 778 produits provenant de 57 sources dans 18 catégories canoniques, dont 9 078 produits en solde — grandes bannières (Metro, Super C, IGA/Voilà, Maxi, Provigo, Walmart…) comme spécialisées et indépendantes (Mayrand, Avril, PA, Tau, Giant Tiger, SAQ…).

# Visite guidée

Le site en 10 écrans — captures de production du 2026-08-28 sur www.food-ka.com.

# 1. Accueil — le catalogue en un coup d'œil

La page d'accueil (food-ka.com) : recherche texte libre, onglets de rayons (18 catégories canoniques), barre de filtres compacte (bannière, marque, prix, format, mentions bio/local/sans gluten…) et grille de cartes produits avec prix, prix unitaire $/100 g et badge de solde. Le ticker temps réel défile en tête de page.

# 2. Aubaines — les rabais de la semaine

/aubaines : tous les produits en solde (9 078 au moment de la capture), triés par rabais, avec prix courant vs prix régulier et pourcentage d'économie — alimenté par le diff engine et price_log.

# 3. Statistiques — le tableau de bord public

/stats : tuiles de synthèse (produits, sources, catégories, soldes, prix moyen), distributions par bannière et par catégorie, fraîcheur des synchronisations — le même module stats v3 qui produit les rapports PDF personnalisés.

# 4. Sources — le registre des bannières

/sources : les 57 bannières connectées avec leur volume et leur dernière synchronisation, plus les bannières non connectables documentées avec leur raison — la transparence plutôt que l'omission silencieuse.

# 5. Contact

/contact : formulaire de contact aux couleurs du Groupe KA, pour signaler une erreur de prix, proposer une bannière ou joindre l'équipe.

# 6. Confidentialité

/confidentialite : politique de confidentialité — ce qui est collecté (compte KA ID, favoris), ce qui ne l'est pas, et l'avertissement sur la nature indicative des prix.

# 7. Accueil filtré — navigation par rayon

Le catalogue filtré par catégorie (/?category=Autres) : chaque rayon est une URL partageable ; les facettes (/api/facets) recalculent les compteurs de bannières et de marques pour le rayon actif.

# 8. Fiche produit — la comparaison inter-bannières

Une fiche produit (/produit/adonis:111033792) : prix courant, prix régulier, prix unitaire $/100 g, historique des variations (price_log) et tableau des équivalents chez les autres bannières (/api/products/{uid}/compare, moteur foodka/matching.py). Fiches rendues côté serveur pour le SEO.

# 9. Profil — le compte KA ID

/profil : le compte KA ID (SSO du Groupe KA — courriel + Google), favoris synchronisés au hub central et valables sur les 12 plateformes ·Ka, recommandations personnalisées « Recommandé pour vous » (moteur ka-id v2).

# 10. Documentation — le guide en ligne

/doc : guide d'utilisation illustré pas à pas (recherche, fiche comparée, aubaines) avec PDF téléchargeable — aussi lié depuis le pied de page du site.

# Galerie DA v3 (2026-08-25) — mobile & desktop

Captures d'époque de la DA v3 « data-épicerie » (mobile 390×844 · desktop 1440×900) — cliquer pour dérouler.

# Mobile

Accueil — recherche ligne fine, KA Tabbar	Aubaines de la semaine	Fiche produit — prix comparés par bannière
Carte des épiceries	Bandeau stats en chiffres	Menu vert profond plein écran

# Desktop

Accueil — onglets rayons soulignés, packshots 12px	Aubaines — échelle de prix à filets
Fiche produit — comparaison multi-bannières	Carte des épiceries du Québec
Répertoire des bannières	Statistiques — 52 700+ produits, 57 bannières

# Nouveautés front-end (2026-08-25)

• DA v3 « data-épicerie » — filtres pupitre sans boîte, onglets rayons soulignés, cartes produits sans cadre (packshot 12px + prix display), échelle de prix à filets, tuiles stats à filets, menu mobile vert profond.
• Refonte UX des filtres épicerie — barre compacte sticky, bottom sheet mobile / modal desktop, presets prix, filtres format (poids/volume/unité) et mentions (bio, local, sans gluten, végane, sans lactose), chips actifs supprimables — API tags/fmt + compteurs facets.
• Recherche mobile — ligne fine au lieu d'une zone de 260 px.
• KA Tabbar v1 — barre de navigation mobile commune Groupe KA.
• Widget ka-agent v4 — cartes produits cliquables et choix en boutons.

🗄️ Les captures d'époque sont conservées dans docs/archive/.

# Fonctionnalités

• Agrégation multi-bannières — un connecteur auto-découvert par bannière (foodka/connectors/), grandes chaînes et épiceries spécialisées, couvrant tout le Québec ; chaque bannière non-connectable est documentée avec sa raison dans data/sources.json.
• Prix unitaire comparable — chaque produit ramené en $/100 g pour comparer l'incomparable.
• Détection des soldes — prix courant vs prix régulier, tri par rabais, historique complet des variations de prix.
• Comparaison inter-bannières — chaque fiche produit montre les équivalents chez les autres bannières (foodka/matching.py).
• Recherche et filtres — catégorie, bannière, marque, fourchette de prix, soldes, texte libre ; tris prix / prix unitaire / rabais / récents.
• Données nutritionnelles — enrichissement des fiches (foodka/nutrition.py).
• Compte KA ID — SSO du Groupe KA (courriel + Google) : un seul compte (ka_id) valable sur toutes les plateformes ·Ka (foodka/auth.py, hubprofile.py), favoris synchronisés au hub central (foodka/hubfav.py).
• Stats Groupe KA — tableau de bord analytique commun avec rapports PDF personnalisés (stats v3 : catalogue, rendu au choix, ReportBuilder — statsdash.py, kapdf.py, pdfgen.py), fenêtre de sync paramétrable pour la supervision api-ka.
• SEO — rendu serveur des fiches et pages (foodka/seo.py).
• PWA installable — design « éditorial sharp » (Space Grotesk, accent lime, ticker temps réel), mobile-first, design system ka-ui partagé, widget KA Agent (bulle de chat IA).
• Fidélité et politesse — aucun prix inventé (price = null si absent), prix régulier incohérent rejeté, throttle entre requêtes, User-Agent identifié, journal sync_log.

# Démarrage rapide

ssh M4M64b && cd ~/apps/food-ka                  # source de vérité : le nœud

# Backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python run.py sync                     # synchroniser toutes les bannières
.venv/bin/python run.py sync metro iga saq       # ...ou seulement certaines (id du registre data/sources.json)
.venv/bin/python run.py serve 8080               # API + PWA + SSR en local

# Frontend (build servi ensuite par FastAPI)
cd frontend && npm install && npm run build && cd ..
cd frontend && npm run dev                       # ...ou serveur de dev Vite

# Tests (normalisation, connecteur Flipp)
.venv/bin/pip install pytest
.venv/bin/python -m pytest tests/ -q

# Validation d'ordre visuel des fiches (standard Groupe KA)
node frontend/scripts/check-order.mjs <uid>

# Boucle de synchronisation continue (ce que fait PM2 en prod)
.venv/bin/python run.py watch 360                # re-parcourt les sources, cycle ≈ 6 h

run.py est le seul point d'entrée : sync [source ...] · watch [minutes] (défaut 360) · serve [port] (défaut 8080).

# Variables d'environnement

Noms seulement — les valeurs vivent dans .env sur le nœud (jamais versionnées).

# Architecture

# Processus PM2

# API principale

S'y ajoutent les routes SSR SEO (/produit/{uid}, sitemaps produits/pages, robots.txt) et les pages /aubaines, /stats, /sources, /doc, /contact, /confidentialite.

# Connecteurs et sources

65 fichiers dans foodka/connectors/ : 57 connecteurs de source (un par bannière active — 1:1 avec les 57 sources actives du registre data/sources.json), 5 bases techniques partagées et le socle base.py / _resilient.py. Le registre compte 61 entrées au 2026-08-24 : 57 actives + 4 bannières non connectables documentées avec leur raison (Bulk Barn, Dollarama, Fermes Lufa, Frenco). Les bannières d'un même groupe partagent une base technique commune :

Connecteurs autonomes (site propre ou API dédiée — 12) : iga (Voilà), walmart, saq (API GraphQL), costco, adonis, avril, mayrand, aubut, tau, tt, loco, maturin.

# Diff engine, price_log & matching inter-bannières

1. Chaque produit normalisé reçoit un hash de contenu ; l'upsert dans SQLite (mode WAL) classe le produit nouveau / modifié / disparu.
2. Chaque variation de prix est écrite dans price_log → historique complet affiché sur la fiche et moteur de la détection des soldes (prix courant vs prix régulier ; prix régulier incohérent rejeté).
3. Le prix unitaire $/100 g est calculé à la normalisation pour rendre les formats comparables entre bannières.
4. Le matching inter-bannières (foodka/matching.py) relie le même produit vendu chez plusieurs bannières — c'est lui qui alimente le tableau de comparaison de la fiche (/api/products/{uid}/compare).
5. Chaque passage de connecteur est journalisé dans sync_log (supervision api-ka, fenêtre de sync paramétrable).

# Données & conformité

• Provenance — chaque produit est lu à la source (site ou API publique de la bannière, circulaires Flipp) ; aucune donnée revendue par un tiers.
• Cadence — le watcher food-ka-sync reparcourt les 57 sources en continu, cycle complet ≈ 6 heures ; chaque passage est journalisé dans sync_log (fraîcheur visible sur /sources et via ?syncs_since_h).
• Fidélité — aucun prix inventé (price = null si absent), prix régulier incohérent rejeté ; les prix des circulaires sont valides pour la durée de la circulaire.
• Politesse de crawl — throttle entre requêtes, retries avec backoff, User-Agent identifié ; l'escalade anti-bot (_resilient.py) n'est utilisée que là où le site le rend nécessaire.
• Avertissement — Food-Ka est un comparateur indépendant, sans affiliation avec les bannières référencées ; les prix sont indicatifs et peuvent varier selon le magasin — le prix en magasin fait foi. Les bannières non connectables restent listées avec leur raison dans le registre plutôt que silencieusement omises.

# Structure du repo

# Documentation

• Guide d'utilisation en ligne : www.food-ka.com/doc — visite guidée pas à pas (accueil, recherche, fiche comparée, aubaines) avec captures d'écran.
• Guide PDF téléchargeable : food-ka-documentation.pdf.
• Le guide est aussi lié depuis le pied de page du site ; ses captures vivent dans frontend/public/doc/img/.

# Historique

# Développement (remote-first)

La source de vérité est le repo git sur le nœud M4M64b (~/apps/food-ka), pas une copie locale. Toute modification se fait sur le nœud via SSH ; le remote origin = spbgit (git perso https://git.spboucher.ai), via l'alias SSH gitsrv configuré sur le nœud → gitsrv:srv/git/food-ka.git (bare repos hébergés sur M3U96a). Pas GitHub.

ssh M4M64b
cd ~/apps/food-ka

# Backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python run.py sync            # synchroniser toutes les bannières (ou : run.py sync metro iga)
.venv/bin/python run.py serve 8080      # servir en local

# Frontend
cd frontend && npm install && npm run build && cd ..

# Après un changement en production
pm2 restart food-ka-web                 # (ou food-ka-sync selon le changement)

# Versionner depuis le nœud (agent forwarding actif)
git add <fichiers> && git commit -m "..." && git push origin main

# Déploiement

• Nœud : M4M64b (Mac Studio, cluster MacLustr) — répertoire ~/apps/food-ka
• Port local : 8097
• Processus PM2 : food-ka-web (API + frontend), food-ka-sync (watcher de synchronisation, cycle ≈ 6 h), food-ka-ngrok (tunnel)
• Exposition publique : tunnel ngrok → https://www.food-ka.com

Philosophie d'exploitation : on ne pousse que le code — le serveur maintient ses données lui-même.

# Écosystème Groupe KA

# Contact

Simon-Pierre Boucher — fondateur, Groupe KA 📧 contact@spboucher.ai

© Groupe KA — Simon-Pierre Boucher · contact@spboucher.ai

Ce repo vit sur spbgit (git.spboucher.ai) — la source de vérité est le clone sur le nœud M4M64b.