spb/food-ka

scripts/gen_connector_docs.py croise data/sources.json, l héritage des
classes connecteurs (familles Flipp/Shopify/WooCommerce/Scrapfly…) et la
BD live (volumétrie, complétude, sync_log, product_links, off_cache,
price_log) pour régénérer docs/connecteurs/ (INDEX.md + fiches).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1. Connecteurs Flipp des grandes bannières (API backflipp publique, 0 crédit
   Scrapfly) : iga_flyer (merchant 4592), metro_flyer (2269, filtre Quebec),
   superc_flyer (2585), maxi_flyer (2349), provigo_flyer (2338),
   walmart_flyer (234, filtre Circulaire), costco_flyer (2596, Grocery).
   Flyers provinciaux verifies sur H2X 1Y4 et G1R 4P5 (memes flyer_id).
   _flipp : tri des flyers par valid_from (la semaine courante gagne sur les
   slugs dupliques semaine courante/a venir).

2. foodka/matching.py : rapprochement inter-bannieres — table product_links
   (group_id, uid) reconstruite apres chaque cycle. Cle marque+nom nettoye+
   format, matching conservateur (marque obligatoire, similarite nom >= 0,86
   avec format identique / 0,95 sans format, jetons numeriques strictement
   egaux — lait 2 % jamais fusionne avec 3,25 %). Une source *_flyer = meme
   banniere que son catalogue. Endpoint GET /api/products/{uid}/compare +
   compteurs matching/nutrition dans /api/stats.

3. foodka/nutrition.py : enrichissement Open Food Facts (voila.ca PDP derriere
   Incapsula et Shopify sans code-barres public -> croisement OFF par
   marque+nom+format, conservateur). search.openfoodfacts.org (le vieux
   cgi/search.pl repond 503) + /api/v2/product/{code} pour les ingredients.
   Nutriscore/NOVA/ecoscore/allergenes/nutriments dans details.off, budget
   100 recherches/cycle, throttle 6 s, cache off_cache (jamais re-cherche).

db.py : tables product_links + off_cache. ingest.py : hooks post-cycle
matching + nutrition (jamais bloquants). sources.json : 54 sources.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- pa_nature : merchant Flipp 3343 disparu -> merchant 3287 (Supermarche PA)
  + filtre flyer_name_filter sur le « Nature Flyer » (60 produits retrouvés)
- Flipp : fiche /flipp/items/{id} via le cache détail (1 appel/item/semaine) ->
  details.fine_print (description, +tx, disclaimer), discount_pct généralisé
  (percent_off), dollars_off, regular_price depuis original_price
- Shopify : details.variants (<=15, multi-formats), created_at/updated_at,
  body_html tronqué à 1500 car., unit_price via grams de variante,
  max_pages 8 -> 24 (pa/nuvo/epipresto/boite_a_grains étaient tronqués à 2000)
- WooCommerce Store API : brand depuis la taxonomie brands, details
  (average_rating, review_count, weight, dimensions, attributes,
  low_stock_remaining, variation_count), unit_price via formatted_weight,
  max_pages 8 -> 32 (aliments_merci tronqué à 800 ; catalogue réel 2765) ;
  akhavan : mêmes details + plafond 4 -> 12 (688 produits)
- db.connect() : WAL + busy_timeout 15 s ; base.get() : retry x3 sur
  ConnectionError/ChunkedEncodingError (parité auto-ka)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Sert /ka-agent.js depuis le statique du frontend et injecte les balises
window.KA_AGENT={site:"food-ka"} + <script src=/ka-agent.js defer> dans
frontend/index.html.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- Vendor du module ka-ui/stats (SPEC.md, kit kacharts.tsx, moteur kapdf.py)
- foodka/statsdash.py : GET /api/stats/dashboard?period=… (contrat SPEC) —
  KPI avec deltas, séries/jour (produits suivis, relevés de prix, prix moyen,
  baisses détectées, nouveautés), donut bannières top 8, top catégories,
  heatmap des relevés, tableaux (top soldes, top baisses, prix par catégorie),
  records & faits marquants ; tout calculé sur products/price_log/sync_log,
  cache serveur 5 min par période
- GET /api/stats/report?period=&mode=complet|synthese : rapport PDF
  Groupe-KA (fpdf2, graphiques vectoriels, wordmark Food·Ka, accent #1f9d55),
  filename kapdf.filename ; correctif kapdf : jamais d en-tête/pied sur la
  couverture (p. 1)
- pages/Stats.tsx : refonte sur le kit kacharts — bandeau KPI, sélecteur de
  période (+ plage personnalisée), courbes interactives, anneau, heatmap,
  tableaux triables/paginés, records, fraîcheur + rafraîchir, boutons PDF ;
  le panier comparatif Food-Ka est conservé (section métier)
- requirements.txt : + fpdf2

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- styles.css : le nav desktop ne tenait pas entre 761 et ~886 px (bouton
  KA ID coupé, +98 px à 768 px) et le badge Groupe KA recréait un
  débordement de 901 à ~1080 px — menu mobile jusqu à 880 px, badge
  masqué jusqu à 1100 px
- index.html : favicon.svg + apple-touch-icon + og:image/twitter:image
  absolus (https://www.food-ka.com/og.png, 1200×630)
- ka-assets/ déplacé vers frontend/public/ (servi à la racine du site)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

frontend/src/ka/ : design system commun Groupe KA requis par le build
(importé par main.tsx, App.tsx et pages/Contact.tsx).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- main.tsx : import de ka/tokens.css (design system commun) avant styles.css
- styles.css : :root réduit à l accent vert marché (#1f9d55 / #e2f5ea / #157a40,
  texte blanc sur accent) + alias --lime/--lime-soft ; socle dédupliqué
  (palette, typo, grain, container, kicker fournis par tokens.css) ; anciens
  rgba encre/papier/lime remplacés par les valeurs tokens ; états actifs et
  CTA passés sur accent-deep + blanc ; classes métier conservées
- Header : badge « Un service Groupe KA » (desktop + menu mobile), lien Contact
- Footer : remplacé par KaFooter (siteId food-ka, lien local Confidentialité)
- Nouvelle page /contact : 3 courriels + rôles, avertissement agrégateur,
  lien hub, liste des 12 sites (ecosystem.json)
- Profil : bouton « Créer un compte » vers groupe-ka.com/connexion
- index.html : titre « Food-Ka — Un service Groupe KA », theme-color et
  favicon aux couleurs du groupe
- Build + déploiement : SSO /api/auth/ka/login vérifié (307 vers
  groupe-ka.com/sso/authorize)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Socle _flipp.py : API publique backflipp.wishabi.com (résolution hebdo du
flyer_id, filtrage merchant_id côté client, catégorisation par mots du nom,
external_id stable marque+nom+format pour l'historique price_log).

Vague 1 — bannières sans e-commerce (Metro/Sobeys affiliés) : richelieu,
marche_ami, bonichoix, tradition, rachelle_bery (réactivée, 2 flyers).
Vague 2 — balayage de l'index Flipp (12 codes postaux, 156 marchands) :
inter_marche (+intl), axep, pasquier, kim_phat (réactivé), marche_ct,
fu_tai, aures, euro_marche, val_mont, bonanza, marche_vegetarien,
pa_nature, aliments_mm. postal_code par connecteur (visibilité régionale).

Tests : fixtures calquées des vraies réponses API (mapping, dédup, garde-fous
prix, frontières de mots du classifieur).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

24 connecteurs actifs (Metro, Super C, IGA/Voilà, Maxi, Provigo, Walmart,
Costco, Adonis, Club Entrepôt, T&T, Akhavan, LOCO, Mayrand, Avril, Tau,
PA, Aubut, Maturin, Giant Tiger, Epipresto, Nuvo, Boîte à Grains,
BocoBoco, Aliments Merci), ~25 500 produits, panier comparatif,
rapport PDF, frontend React « marché frais », déployé sur M4M64b
(www.food-ka.com).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>