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

Simon-Pierre Boucher committed 28 days ago (Aug 29, 2026) parent 85e363e

11 changed files +26 −33

modified README.md +26 −33

		`@@ -20,49 +20,39 @@`
20	20	<img src="https://img.shields.io/badge/Groupe-KA-b7f000?style=flat-square" alt="Groupe KA">
21	21	</p>
22	22
23		−Immo-Ka est un agrégateur immobilier indépendant pour la province de Québec. Chercher une propriété, c'est normalement jongler entre les sites de RE/MAX, Royal LePage, Sutton, Via Capitale, Century 21, DuProprio et des dizaines d'autres bannières — chacun avec sa navigation, ses filtres et son format. Immo-Ka retourne le problème : un connecteur dédié par source (105 connecteurs enregistrés — flux centraux de bannières, sous-agences en plan B, plateformes sans courtier) visite chaque site, normalise chaque annonce vers un schéma unique (`PropertyListing`), déduplique par numéro Centris et détecte les changements en continu, avec lien direct vers l'annonce originale.
	23	+Immo-Ka est un agrégateur immobilier indépendant pour la province de Québec. Chercher une propriété, c'est normalement jongler entre les sites de RE/MAX, Royal LePage, Sutton, Via Capitale, Century 21, DuProprio et des dizaines d'autres bannières — chacun avec sa navigation, ses filtres et son format. Immo-Ka retourne le problème : un connecteur dédié par source (123 connecteurs enregistrés — flux centraux de bannières, sous-agences en plan B, plateformes sans courtier) visite chaque site, normalise chaque annonce vers un schéma unique (`PropertyListing`), déduplique par numéro Centris et détecte les changements en continu, avec lien direct vers l'annonce originale.
24	24
25		−Les sites d'agences n'offrent pas de webhooks : Immo-Ka en reproduit l'équivalent par synchronisation périodique + hash de contenu — ajouts, changements de prix et retraits (propriété vendue) détectés automatiquement, avec délai de grâce contre les ratés ponctuels. Couverture (métriques de l'agrégat) : 67 700+ propriétés actives (67 705 au 2026-08-24), 48 sources, 22 bannières, 159 sous-agences, 3 262 villes. C'est le pendant « à vendre » de [Lou-Ka](https://www.lou-ka.com) (location), branché sur le moteur d'estimation [Vrai-Prix](https://www.vrai-prix.com) et sur le compte unique KA ID du Groupe KA.
	25	+Les sites d'agences n'offrent pas de webhooks : Immo-Ka en reproduit l'équivalent par synchronisation périodique + hash de contenu — ajouts, changements de prix et retraits (propriété vendue) détectés automatiquement, avec délai de grâce contre les ratés ponctuels. Couverture (métriques de l'agrégat) : 70 500+ propriétés actives (70 535 au 2026-08-28), 66 sources, 22 bannières, 159 sous-agences, 3 331 villes. C'est le pendant « à vendre » de [Lou-Ka](https://www.lou-ka.com) (location), branché sur le moteur d'estimation [Vrai-Prix](https://www.vrai-prix.com) et sur le compte unique KA ID du Groupe KA.
26	26
27	27	## Visite guidée
28	28
29		−Captures du 2026-08-25 — refonte éditoriale v2 (mobile 390×844 · desktop 1440×900).
30		−
31		−### Mobile
	29	+Captures du 2026-08-28 — desktop 1440×900 · mobile 390×844.
32	30
33	31	<table>
34	32	<tr>
35		− <td align="center"><img src="docs/screenshots/mobile/home.webp" width="240" alt="Accueil mobile"><br><sub><b>Accueil — héro typographique, compteurs live</b></sub></td>
36		− <td align="center"><img src="docs/screenshots/mobile/resultats.webp" width="240" alt="Résultats mobile"><br><sub><b>Propriétés à Montréal</b></sub></td>
37		− <td align="center"><img src="docs/screenshots/mobile/fiche.webp" width="240" alt="Fiche mobile"><br><sub><b>Fiche v2 — galerie, prix, badge Vrai-Prix</b></sub></td>
	33	+ <td align="center" width="50%"><a href="https://www.immo-ka.com/"><img src="docs/screenshots/01-accueil.jpg" width="420" alt="Accueil"></a><br><sub><b>Accueil</b> — héro typographique, recherche instantanée, compteurs live de l'agrégat</sub></td>
	34	+ <td align="center" width="50%"><a href="https://www.immo-ka.com/?view=carte"><img src="docs/screenshots/09-accueil.jpg" width="420" alt="Vue carte"></a><br><sub><b>Vue carte Ka Maps</b> — grappes de prix Mapbox GL 3D, marqueurs colorés selon l'écart au Vrai-Prix, « rechercher en déplaçant la carte »</sub></td>
38	35	</tr>
39	36	<tr>
40		− <td align="center"><img src="docs/screenshots/mobile/stats.webp" width="240" alt="Stats mobile"><br><sub><b>Observatoire du marché</b></sub></td>
41		− <td align="center"><img src="docs/screenshots/mobile/inspecteurs.webp" width="240" alt="Inspecteurs mobile"><br><sub><b>Annuaire des inspecteurs</b></sub></td>
42		− <td align="center"><img src="docs/screenshots/mobile/menu-mobile.webp" width="240" alt="Menu mobile"><br><sub><b>Tabbar flottante + nav v2</b></sub></td>
	37	+ <td align="center"><img src="docs/screenshots/02-propriete-abbeyandolivier-3A11701844-5334-rue-waverly-montre.jpg" width="420" alt="Fiche propriété"><br><sub><b>Fiche propriété</b> (5334 rue Waverly, Le Plateau-Mont-Royal) — galerie, prix + badge Vrai-Prix, caractéristiques Centris, route SEO <code>/propriete/:uid/:slug</code></sub></td>
	38	+ <td align="center"><a href="https://www.immo-ka.com/taux-hypothecaires"><img src="docs/screenshots/03-taux-hypothecaires.jpg" width="420" alt="Taux hypothécaires"></a><br><sub><b>Taux hypothécaires</b> — comparateur de taux par prêteur + calculateur et intelligence de financement</sub></td>
43	39	</tr>
44		−</table>
45		−
46		−### Desktop
47		−
48		−<table>
49	40	<tr>
50		− <td align="center"><img src="docs/screenshots/desktop/home.webp" width="420" alt="Accueil desktop"><br><sub><b>Accueil — DA premium sans boîtes, recherche soulignée</b></sub></td>
51		− <td align="center"><img src="docs/screenshots/desktop/resultats.webp" width="420" alt="Résultats desktop"><br><sub><b>Résultats — grille uniforme, filtres par type</b></sub></td>
	41	+ <td align="center"><a href="https://www.immo-ka.com/stats"><img src="docs/screenshots/04-stats.jpg" width="420" alt="Observatoire stats"></a><br><sub><b>Observatoire <code>/stats</code></b> — 70 500+ annonces actives, volumes par type et bannière, écart prix demandé vs estimation Vrai-Prix, rapport PDF</sub></td>
	42	+ <td align="center"><a href="https://www.immo-ka.com/agences"><img src="docs/screenshots/05-agences.jpg" width="420" alt="Agences"></a><br><sub><b>Agences</b> — registre bannière → sous-agence, comptes d'annonces dédupliqués</sub></td>
52	43	</tr>
53	44	<tr>
54		− <td align="center"><img src="docs/screenshots/desktop/fiche.webp" width="420" alt="Fiche propriété"><br><sub><b>Fiche v2 — sections à filets, icônes contextuelles</b></sub></td>
55		− <td align="center"><img src="docs/screenshots/desktop/fiche-analyses.webp" width="420" alt="Analyses"><br><sub><b>Fiche — jauge Vrai-Prix P10–P90, quartier, panneaux stats</b></sub></td>
	45	+ <td align="center"><a href="https://www.immo-ka.com/demenageurs"><img src="docs/screenshots/06-demenageurs.jpg" width="420" alt="Déménageurs"></a><br><sub><b>Annuaire des déménageurs</b> — 565 fiches, partagé avec Lou·Ka</sub></td>
	46	+ <td align="center"><a href="https://www.immo-ka.com/inspecteurs"><img src="docs/screenshots/07-inspecteurs.jpg" width="420" alt="Inspecteurs"></a><br><sub><b>Annuaire des inspecteurs en bâtiment</b> — 542 fiches</sub></td>
56	47	</tr>
57	48	<tr>
58		− <td align="center"><img src="docs/screenshots/desktop/inspecteurs.webp" width="420" alt="Inspecteurs"><br><sub><b>Annuaire des inspecteurs en bâtiment (542 fiches)</b></sub></td>
59		− <td align="center"><img src="docs/screenshots/desktop/demenageurs.webp" width="420" alt="Déménageurs"><br><sub><b>Annuaire des déménageurs (565 fiches, avec Lou·Ka)</b></sub></td>
60		− </tr>
61		− <tr>
62		− <td align="center" colspan="2"><img src="docs/screenshots/desktop/stats.webp" width="640" alt="Stats"><br><sub><b>Observatoire — 69 500+ propriétés</b></sub></td>
	49	+ <td align="center"><a href="https://www.immo-ka.com/contact"><img src="docs/screenshots/08-contact.jpg" width="420" alt="Contact"></a><br><sub><b>Contact</b> — formulaire + coordonnées du Groupe KA</sub></td>
	50	+ <td align="center"><img src="docs/screenshots/10-accueil-mobile.jpg" width="240" alt="Accueil mobile"><br><sub><b>Accueil mobile</b> (390×844) — tabbar flottante, même langage que Lou-Ka v2</sub></td>
63	51	</tr>
64	52	</table>
65	53
	54	+> 🗄️ Les captures de la refonte v2 (2026-08-25, webp) sont conservées dans [`docs/screenshots/desktop/`](docs/screenshots/desktop/) et [`docs/screenshots/mobile/`](docs/screenshots/mobile/) ; les captures d'époque dans [`docs/archive/`](docs/archive/).
	55	+
66	56	### Nouveautés front-end (2026-08-25)
67	57
68	58	- Refonte éditoriale v2 — accueil et fiche propriété en DA premium « sans boîtes » ; grille desktop uniforme, header sans débordement.
		`@@ -72,8 +62,6 @@ Les sites d'agences n'offrent pas de webhooks : Immo-Ka en reproduit l'équivale`
72	62	- Annuaires — inspecteurs en bâtiment (542) et déménageurs (565, partagé avec Lou·Ka).
73	63	- Widget ka-agent v4 — cartes d'annonces cliquables et choix en boutons.
74	64
75		−> 🗄️ Les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).
76		−
77	65	## Fonctionnalités
78	66
79	67	- Recherche & filtres — texte libre (adresse, ville, n° MLS), ville + secteur, type, agence, prix, chambres, salles de bain, superficie ; tri par prix ou récence ; état encodé dans l'URL (partageable).
		`@@ -82,12 +70,14 @@ Les sites d'agences n'offrent pas de webhooks : Immo-Ka en reproduit l'équivale`
82	70	- Estimation Vrai-Prix — valeur marchande estimée (modèle hédonique + comparables) : jauge P10–P90, verdict sur-évalué / aligné / sous l'estimation.
83	71	- Rôle d'évaluation foncière — valeur au rôle terrain/bâtiment, année de construction et superficies officielles, jointes localement depuis la base Vrai-Prix.
84	72	- Historique de prix — baisses et hausses du prix demandé horodatées (table `price_log`) + jours sur le marché.
	73	+- Taux hypothécaires & financement — page `/taux-hypothecaires` : taux courants par prêteur, calculateur de paiements et « intelligence » de financement (`/api/mortgage/*`) appliqués au prix de la fiche.
85	74	- Quartier — aire de diffusion du recensement : revenu médian, loyer moyen, % locataires, proximité épiceries/parcs/soins (StatCan), îlot de chaleur (INSPQ).
86	75	- Couches territoriales — registre des loyers, zones inondables (BDZI), qualité de l'air, prix de l'essence, commerces et transport en commun, estimation Hydro-Québec précalculée lors de la sync.
87	76	- Stats — tableau de bord `/stats` : volumes par type et bannière, écart prix demandé vs estimation Vrai-Prix, panneaux territoire + rapport PDF Groupe-KA.
88	77	- Agences — registre par bannière → sous-agence, comptes d'annonces dédupliqués.
	78	+- Annuaires pratiques — inspecteurs en bâtiment (`/inspecteurs`) et déménageurs (`/demenageurs`, base partagée avec Lou·Ka).
89	79	- KA ID & favoris — SSO du hub groupe-ka.com (JWT HS256), favoris partagés sur toutes les plateformes Ka ; widget de chat KA Agent intégré.
90		−- SEO programmatique — HTML complet rendu côté serveur, une page indexable par ville / type / ville+type, sitemaps et données structurées.
	80	+- SEO programmatique — HTML complet rendu côté serveur, une page indexable par ville / type / ville+type, route canonique `/propriete/:uid/:slug`, sitemaps et données structurées.
91	81
92	82	## API principale
93	83
		`@@ -100,15 +90,17 @@ Toutes les données servies au frontend passent par une API JSON publique (FastA`
100	90	\| `GET /api/listings.geojson` \| flux GeoJSON pour la carte Ka Maps (grappes + marqueurs) \|
101	91	\| `GET /api/facets` \| facettes dynamiques (villes, types, agences, fourchettes de prix) \|
102	92	\| `GET /api/sources` · `GET /api/agencies` \| état des connecteurs et registre bannières → sous-agences \|
	93	+\| `GET /api/mortgage/providers` · `POST /api/mortgage/calculate` · `/api/mortgage/intelligence` \| taux hypothécaires par prêteur, calculateur et analyse de financement \|
103	94	\| `GET /api/hydro` · `/api/commerces` · `/api/air` · `/api/gaz` · `/api/inondation` \| couches territoriales d'une fiche \|
104	95	\| `GET /api/stats` · `/api/stats/dashboard` \| métriques agrégées et tableau de bord \|
105	96	\| `GET /api/stats/report` · `/api/stats/catalog` · `POST /api/stats/report/custom` \| rapports PDF Groupe-KA (standard et personnalisés) \|
	97	+\| `GET /api/auth/me` · `/api/favorites` · `POST /api/favorites/toggle` \| session KA ID et favoris partagés \|
106	98	\| `POST /api/sync` \| déclenchement d'une synchronisation \|
107	99	\| `GET /robots.txt` · `/sitemap.xml` · `/sitemaps/{name}` · `/api/seo/resolve` \| infrastructure SEO \|
108	100
109	101	## Connecteurs & sources
110	102
111		−105 connecteurs enregistrés (paquet `immoka/connectors/`), un par source, orchestrés par la boucle d'ingestion :
	103	+123 connecteurs enregistrés (paquet `immoka/connectors/`), un par source, orchestrés par la boucle d'ingestion :
112	104
113	105	\| Famille de sources \| Exemples \| Technique d'extraction \|
114	106	\|---\|---\|---\|
		`@@ -116,18 +108,19 @@ Toutes les données servies au frontend passent par une API JSON publique (FastA`
116	108	\| Sous-agences (plan B) \| 159 bureaux — KW Distinction/Prestige/Urbain, eXp Québec, Barnes, Engel & Völkers, BHHS… \| API du site du bureau, JSON-LD, sitemaps \|
117	109	\| Sans courtier / petites annonces \| DuProprio, Kijiji, LesPAC, Facebook Marketplace \| API publiques + extraction dédiée \|
118	110	\| Sites vitrines & SPA anti-bot \| agences boutique (Charisma, Imcha, Immeubles Stuart…), GuideHabitation \| JSON-LD génériques, sitemaps, Firecrawl en secours \|
	111	+\| Extension Ontario (en pause) \| connecteur générique RealtyPress + monstres CREA DDF (revelrealty, codygroup…) \| CREA DDF / RealtyPress — suspendue (`docs/ONTARIO-PAUSE.md`), rien d'effacé \|
119	112
120	113	- Normalisation : chaque annonce est projetée vers le schéma unique `PropertyListing` (`immoka/schema.py`).
121		−- Dédup : par numéro Centris (`dup_hidden`) — une propriété affichée par 3 sites = 1 fiche, sources créditées.
	114	+- Dédup : par numéro Centris (`dup_hidden`) — une propriété affichée par 3 sites = 1 fiche, sources créditées ; en front, priorité au courtier + box « Aussi publiée sur… ».
122	115	- Détection de changements : upsert par hash de contenu ; retraits avec délai de grâce contre les ratés ponctuels d'un site.
123		−- Qualité : couche `quality.py` + `imgaudit.py` — annonces publiées vs quarantaine, audit des images, golden record.
	116	+- Qualité : couche `quality.py` + `imgaudit.py` — annonces publiées vs quarantaine (fiches incomplètes ou douteuses retenues), audit des images (placeholders, doublons, formats), golden record par propriété.
124	117	- Cadence : resynchronisation complète aux 4 heures (`run.py watch 240`, processus `immo-ka-sync`), enrichissements (géocodage, POI, quartier, Vrai-Prix, Hydro-Québec) appliqués au fil de la sync.
125	118
126	119	## Architecture
127	120
128	121	\| Composant \| Rôle \|
129	122	\|---\|---\|
130		−\| `immoka/connectors/` \| 105 connecteurs enregistrés (API JSON internes — Meilisearch, Algolia, source.immo, wp-json —, JSON-LD, sitemaps, Firecrawl pour les sites SPA/anti-bot) \|
	123	+\| `immoka/connectors/` \| 123 connecteurs enregistrés (API JSON internes — Meilisearch, Algolia, source.immo, wp-json —, JSON-LD, sitemaps, Firecrawl pour les sites SPA/anti-bot) \|
131	124	\| `immoka/ingest.py` + `normalize.py` + `schema.py` \| boucle de sync : normalisation vers `PropertyListing`, upsert par hash de contenu, dédup Centris (`dup_hidden`), délai de grâce sur les retraits \|
132	125	\| `immoka/web.py` + `seo.py` \| FastAPI : API JSON, rendu SEO serveur, service du build frontend \|
133	126	\| Enrichissement \| `geocode.py`, `poi.py`, `quartier.py`, `vraiprix.py`/`vraiprix_local.py`, `hydro.py`, `inondation.py`, `air.py`, `gaz.py`, `commerces.py`, `quality.py`/`imgaudit.py` (couche qualité + quarantaine) \|
		`@@ -149,7 +142,7 @@ Toutes les données servies au frontend passent par une API JSON publique (FastA`
149	142	\| `immoka/` \| paquet Python : connecteurs, ingestion, API/SSR, enrichissements, stats \|
150	143	\| `frontend/` \| SPA React 18 + Vite + TypeScript (pages, composants, ka-maps, ka-ui) \|
151	144	\| `data/` \| bases SQLite (immoka.db + bases annexes) et registres d'agences JSON \|
152		−\| `docs/` \| captures d'écran, docs des connecteurs, rapports de validation \|
	145	+\| `docs/` \| captures d'écran (visite guidée + archives), docs des connecteurs, rapports de validation \|
153	146	\| `scripts/` \| outillage (génération des docs connecteurs, rafraîchissement Via Capitale, validation du rendu) \|
154	147	\| `run.py` / `requirements.txt` \| point d'entrée CLI (`sync`, `watch`, `serve`, `list`, `geocode`, `poi`, `quartier`, …) et dépendances backend \|
155	148

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

Binary file not shown.

added docs/screenshots/02-propriete-abbeyandolivier-3A11701844-5334-rue-waverly-montre.jpg +0 −0

Binary file not shown.

added docs/screenshots/03-taux-hypothecaires.jpg +0 −0

Binary file not shown.

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

Binary file not shown.

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

Binary file not shown.

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

Binary file not shown.

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

Binary file not shown.

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

Binary file not shown.

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

Binary file not shown.

added docs/screenshots/10-accueil-mobile.jpg +0 −0

Binary file not shown.