docs: README ultra détaillé + visite guidée en 10 captures

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

Simon-Pierre Boucher committed 29 days ago (Aug 29, 2026) parent b1f13ce

11 changed files +75 −5

modified README.md +75 −5

		`@@ -37,13 +37,78 @@`
37	37
38	38	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.
39	39
40		−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-24, le catalogue compte 50 892 produits provenant de 57 sources dans 18 catégories canoniques, dont 8 818 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…).
	40	+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…).
41	41
42	42	## Visite guidée
43	43
44		−Captures du 2026-08-25 — DA v3 « data-épicerie » (mobile 390×844 · desktop 1440×900).
	44	+Le site en 10 écrans — captures de production du 2026-08-28 sur [www.food-ka.com](https://www.food-ka.com).
45	45
46		−### Mobile
	46	+### 1. Accueil — le catalogue en un coup d'œil
	47	+
	48	+<p align="center"><img src="docs/screenshots/01-accueil.jpg" width="880" alt="Accueil Food-Ka"></p>
	49	+
	50	+La page d'accueil ([food-ka.com](https://www.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.
	51	+
	52	+### 2. Aubaines — les rabais de la semaine
	53	+
	54	+<p align="center"><img src="docs/screenshots/02-aubaines.jpg" width="880" alt="Page aubaines"></p>
	55	+
	56	+[/aubaines](https://www.food-ka.com/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`.
	57	+
	58	+### 3. Statistiques — le tableau de bord public
	59	+
	60	+<p align="center"><img src="docs/screenshots/03-stats.jpg" width="880" alt="Page statistiques"></p>
	61	+
	62	+[/stats](https://www.food-ka.com/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.
	63	+
	64	+### 4. Sources — le registre des bannières
	65	+
	66	+<p align="center"><img src="docs/screenshots/04-sources.jpg" width="880" alt="Page sources"></p>
	67	+
	68	+[/sources](https://www.food-ka.com/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.
	69	+
	70	+### 5. Contact
	71	+
	72	+<p align="center"><img src="docs/screenshots/05-contact.jpg" width="880" alt="Page contact"></p>
	73	+
	74	+[/contact](https://www.food-ka.com/contact) : formulaire de contact aux couleurs du Groupe KA, pour signaler une erreur de prix, proposer une bannière ou joindre l'équipe.
	75	+
	76	+### 6. Confidentialité
	77	+
	78	+<p align="center"><img src="docs/screenshots/06-confidentialite.jpg" width="880" alt="Page confidentialité"></p>
	79	+
	80	+[/confidentialite](https://www.food-ka.com/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.
	81	+
	82	+### 7. Accueil filtré — navigation par rayon
	83	+
	84	+<p align="center"><img src="docs/screenshots/07-accueil.jpg" width="880" alt="Accueil filtré par catégorie"></p>
	85	+
	86	+Le catalogue filtré par catégorie ([/?category=Autres](https://www.food-ka.com/?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.
	87	+
	88	+### 8. Fiche produit — la comparaison inter-bannières
	89	+
	90	+<p align="center"><img src="docs/screenshots/08-produit-adonis-111033792.jpg" width="880" alt="Fiche produit Adonis"></p>
	91	+
	92	+Une fiche produit ([/produit/adonis:111033792](https://www.food-ka.com/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.
	93	+
	94	+### 9. Profil — le compte KA ID
	95	+
	96	+<p align="center"><img src="docs/screenshots/09-profil.jpg" width="880" alt="Page profil KA ID"></p>
	97	+
	98	+[/profil](https://www.food-ka.com/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).
	99	+
	100	+### 10. Documentation — le guide en ligne
	101	+
	102	+<p align="center"><img src="docs/screenshots/10-doc.jpg" width="880" alt="Page documentation"></p>
	103	+
	104	+[/doc](https://www.food-ka.com/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.
	105	+
	106	+### Galerie DA v3 (2026-08-25) — mobile & desktop
	107	+
	108	+<details>
	109	+<summary>Captures d'époque de la DA v3 « data-épicerie » (mobile 390×844 · desktop 1440×900) — cliquer pour dérouler.</summary>
	110	+
	111	+#### Mobile
47	112
48	113	<table>
49	114	<tr>
		`@@ -58,7 +123,7 @@ Les épiceries n'offrent pas de webhooks ; Food-Ka en reproduit l'équivalent :`
58	123	</tr>
59	124	</table>
60	125
61		−### Desktop
	126	+#### Desktop
62	127
63	128	<table>
64	129	<tr>
		`@@ -75,6 +140,8 @@ Les épiceries n'offrent pas de webhooks ; Food-Ka en reproduit l'équivalent :`
75	140	</tr>
76	141	</table>
77	142
	143	+</details>
	144	+
78	145	### Nouveautés front-end (2026-08-25)
79	146
80	147	- 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.
		@@ -217,7 +284,7 @@ Connecteurs autonomes (site propre ou API dédiée — 12) : `iga` (Voilà),
217	284	\| `foodka/` \| Backend Python : schéma Product, normalisation, ingestion, db, web, seo, matching inter-bannières, nutrition, auth KA ID, favoris, stats, PDF + `connectors/` \|
218	285	\| `frontend/` \| PWA React 18 + Vite + TypeScript (build servi par FastAPI) — inclut la page `/doc` (`frontend/public/doc/`) \|
219	286	\| `data/` \| `foodka.db` (SQLite) + `sources.json` (registre des 61 bannières, raisons des non-connectables incluses) \|
220		−\| `docs/` \| Captures d'écran + documentation générée des connecteurs \|
	287	+\| `docs/` \| Captures d'écran (`screenshots/` : visite guidée 2026-08-28 + galeries mobile/desktop DA v3, `archive/` : captures d'époque) + documentation générée des connecteurs \|
221	288	\| `scripts/` \| Outillage (`gen_connector_docs.py`) \|
222	289	\| `tests/` \| Tests pytest (`test_normalize.py`, `test_flipp.py`) \|
223	290
		@@ -238,6 +305,9 @@ Connecteurs autonomes (site propre ou API dédiée — 12) : `iga` (Voilà),
238	305	\| 2026-08-18 \| `114aa76` \| Matching inter-bannières : `MAX_BLOCK` 400 → 3000 (fenêtre triée, rebuild mesuré à 7 s) \|
239	306	\| 2026-08-23 \| `8acf4c4` \| Stats v3 : rapports PDF personnalisés (catalogue, ReportBuilder) \|
240	307	\| 2026-08-24 \| `3a264e7` \| Page documentation `/doc` (guide + captures) + PDF téléchargeable \|
	308	+\| 2026-08-25 \| `c740a48` \| Campagne visuelle : galerie WebP mobile + desktop (DA v3 « data-épicerie ») \|
	309	+\| 2026-08-26 \| `a4e75ac` \| ka-id v2 : personnalisation Groupe KA (journal serveur, reranking, badge « Recommandé pour vous ») \|
	310	+\| 2026-08-28 \| — \| README ultra détaillé + visite guidée en 10 captures (`docs/screenshots/`) \|
241	311
242	312	## Développement (remote-first)
243	313

added docs/screenshots/01-accueil.jpg +0 −0

Binary file not shown.

added docs/screenshots/02-aubaines.jpg +0 −0

Binary file not shown.

added docs/screenshots/03-stats.jpg +0 −0

Binary file not shown.

added docs/screenshots/04-sources.jpg +0 −0

Binary file not shown.

added docs/screenshots/05-contact.jpg +0 −0

Binary file not shown.

added docs/screenshots/06-confidentialite.jpg +0 −0

Binary file not shown.

added docs/screenshots/07-accueil.jpg +0 −0

Binary file not shown.

added docs/screenshots/08-produit-adonis-111033792.jpg +0 −0

Binary file not shown.

added docs/screenshots/09-profil.jpg +0 −0

Binary file not shown.

added docs/screenshots/10-doc.jpg +0 −0

Binary file not shown.