docs: README v2 — galerie multi-pages, style du site, documentation, contact
1 changed file +107 −30
modified
README.md
+107 −30
@@ -1,27 +1,57 @@ | ||
| 1 | −# Immo·Ka | |
| 1 | +<p align="center"> | |
| 2 | + <a href="https://www.immo-ka.com"><img src="https://www.immo-ka.com/og.png" width="760" alt="Immo·Ka — Toutes les propriétés à vendre"></a> | |
| 3 | +</p> | |
| 4 | + | |
| 5 | +<h1 align="center">Immo·Ka</h1> | |
| 2 | 6 | |
| 3 | −**Toutes les propriétés à vendre du Québec — maisons, condos, plex et terrains — réunies au même endroit, toujours à jour.** | |
| 7 | +<p align="center"><b>Toutes les propriétés à vendre du Québec — maisons, condos, plex et terrains — réunies au même endroit, toujours à jour.</b></p> | |
| 4 | 8 | |
| 5 | −[](https://www.immo-ka.com) | |
| 6 | − | |
| 7 | − | |
| 8 | − | |
| 9 | − | |
| 10 | − | |
| 11 | − | |
| 12 | − | |
| 13 | − | |
| 9 | +<p align="center"> | |
| 10 | + <a href="https://www.immo-ka.com"><img src="https://img.shields.io/website?url=https%3A%2F%2Fwww.immo-ka.com&style=flat-square&label=www.immo-ka.com&up_color=e23744" alt="Site"></a> | |
| 11 | + <a href="https://www.immo-ka.com/doc/"><img src="https://img.shields.io/badge/📖_documentation-%2Fdoc-e23744?style=flat-square" alt="Documentation"></a> | |
| 12 | + <a href="https://www.immo-ka.com/doc/immo-ka-documentation.pdf"><img src="https://img.shields.io/badge/guide-PDF-e23744?style=flat-square" alt="Guide PDF"></a> | |
| 13 | + <img src="https://img.shields.io/badge/n%C5%93ud-M4M64a-1f6feb?style=flat-square" alt="Nœud"> | |
| 14 | + <img src="https://img.shields.io/badge/port-8096-555?style=flat-square" alt="Port"> | |
| 15 | + <img src="https://img.shields.io/badge/process-PM2-2b037a?style=flat-square" alt="PM2"> | |
| 16 | + <img src="https://img.shields.io/badge/Python-FastAPI-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python FastAPI"> | |
| 17 | + <img src="https://img.shields.io/badge/React_18-Vite_%2B_TS-61dafb?style=flat-square&logo=react&logoColor=black" alt="React 18"> | |
| 18 | + <img src="https://img.shields.io/badge/SQLite-WAL-003b57?style=flat-square&logo=sqlite&logoColor=white" alt="SQLite"> | |
| 19 | + <img src="https://img.shields.io/badge/Ka_Maps-Mapbox_GL_3D-4264fb?style=flat-square" alt="Ka Maps"> | |
| 20 | + <img src="https://img.shields.io/badge/Groupe-KA-b7f000?style=flat-square" alt="Groupe KA"> | |
| 21 | +</p> | |
| 14 | 22 | |
| 15 | 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. |
| 16 | 24 | |
| 17 | 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) : **57 900+ propriétés actives**, **22 bannières**, **159 sous-agences**, **2 825 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. |
| 18 | 26 | |
| 19 | −## Captures d'écran | |
| 20 | − | |
| 21 | −<p align="center"> | |
| 22 | − <img src="docs/screenshots/immo-ka-desktop.png" width="640" alt="Accueil — desktop"> | |
| 23 | − <img src="docs/screenshots/immo-ka-mobile.png" width="200" alt="Accueil — mobile"> | |
| 24 | −</p> | |
| 27 | +## Visite guidée | |
| 28 | + | |
| 29 | +<table> | |
| 30 | + <tr> | |
| 31 | + <td align="center"><img src="frontend/public/doc/img/etape1.png" width="420"><br><sub><b>Accueil — le marché en direct : ruban des bannières, compteurs live et recherche (adresse, ville, n° MLS)</b></sub></td> | |
| 32 | + <td align="center"><img src="frontend/public/doc/img/etape2.png" width="420"><br><sub><b>Résultats filtrés — condos à Montréal : cartes photo, prix, chambres/sdb et bannière source</b></sub></td> | |
| 33 | + </tr> | |
| 34 | + <tr> | |
| 35 | + <td align="center"><img src="frontend/public/doc/img/etape3.png" width="420"><br><sub><b>Fiche détail — galerie (48 photos) et mini-carte 3D avec le bâtiment de l'annonce en évidence</b></sub></td> | |
| 36 | + <td align="center"><img src="frontend/public/doc/img/etape4.png" width="420"><br><sub><b>Carte Ka Maps — grappes de prix sur la région de Québec, « rechercher en déplaçant la carte », bascule 2D/3D</b></sub></td> | |
| 37 | + </tr> | |
| 38 | + <tr> | |
| 39 | + <td align="center"><img src="docs/screenshots/carte.png" width="420"><br><sub><b>Vue liste + carte à l'échelle de la province — marqueurs colorés selon l'écart à l'estimation Vrai-Prix</b></sub></td> | |
| 40 | + <td align="center"><img src="docs/screenshots/grille.png" width="420"><br><sub><b>Grille de résultats — maisons, condos et terrains avec compte de photos et n° MLS</b></sub></td> | |
| 41 | + </tr> | |
| 42 | + <tr> | |
| 43 | + <td align="center"><img src="docs/screenshots/listing.png" width="420"><br><sub><b>Fiche — prix demandé, jauge Vrai-Prix P10–P90 (verdict « aligné sur l'estimation ») et courtier source</b></sub></td> | |
| 44 | + <td align="center"><img src="docs/screenshots/listing-quartier.png" width="420"><br><sub><b>Fiche — emplacement (isochrones 5/15 min à pied) et panneau quartier issu du recensement</b></sub></td> | |
| 45 | + </tr> | |
| 46 | + <tr> | |
| 47 | + <td align="center"><img src="docs/screenshots/ville.png" width="420"><br><sub><b>Page ville SEO — « Propriétés à vendre à Québec », une page indexable par ville / type</b></sub></td> | |
| 48 | + <td align="center"><img src="docs/screenshots/agences.png" width="420"><br><sub><b>Registre des agences — chaque bannière éclatée par sous-agence, comptes dédupliqués par Centris</b></sub></td> | |
| 49 | + </tr> | |
| 50 | + <tr> | |
| 51 | + <td align="center"><img src="docs/screenshots/stats.png" width="420"><br><sub><b>Tableau de bord /stats — le marché agrégé : volumes par type et par agence, prix moyens</b></sub></td> | |
| 52 | + <td align="center"><img src="docs/screenshots/immo-ka-mobile.png" width="420"><br><sub><b>Mobile — accueil avec filtres flottants, puces de types et widget KA Agent</b></sub></td> | |
| 53 | + </tr> | |
| 54 | +</table> | |
| 25 | 55 | |
| 26 | 56 | ## Fonctionnalités |
| 27 | 57 | |
@@ -38,6 +68,40 @@ Les sites d'agences n'offrent pas de webhooks : Immo-Ka en reproduit l'équivale | ||
| 38 | 68 | - **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é. |
| 39 | 69 | - **SEO programmatique** — HTML complet rendu côté serveur, une page indexable par ville / type / ville+type, sitemaps et données structurées. |
| 40 | 70 | |
| 71 | +## API principale | |
| 72 | + | |
| 73 | +Toutes les données servies au frontend passent par une API JSON publique (FastAPI) : | |
| 74 | + | |
| 75 | +| Endpoint | Rôle | | |
| 76 | +|---|---| | |
| 77 | +| `GET /api/listings` | recherche paginée : texte libre, ville, type, agence, prix, chambres/sdb, superficie, tri | | |
| 78 | +| `GET /api/listings/{uid}` | fiche complète d'une annonce (photos, pièces, enrichissements, estimation) | | |
| 79 | +| `GET /api/listings.geojson` | flux GeoJSON pour la carte Ka Maps (grappes + marqueurs) | | |
| 80 | +| `GET /api/facets` | facettes dynamiques (villes, types, agences, fourchettes de prix) | | |
| 81 | +| `GET /api/sources` · `GET /api/agencies` | état des connecteurs et registre bannières → sous-agences | | |
| 82 | +| `GET /api/hydro` · `/api/commerces` · `/api/air` · `/api/gaz` · `/api/inondation` | couches territoriales d'une fiche | | |
| 83 | +| `GET /api/stats` · `/api/stats/dashboard` | métriques agrégées et tableau de bord | | |
| 84 | +| `GET /api/stats/report` · `/api/stats/catalog` · `POST /api/stats/report/custom` | rapports PDF Groupe-KA (standard et personnalisés) | | |
| 85 | +| `POST /api/sync` | déclenchement d'une synchronisation | | |
| 86 | +| `GET /robots.txt` · `/sitemap.xml` · `/sitemaps/{name}` · `/api/seo/resolve` | infrastructure SEO | | |
| 87 | + | |
| 88 | +## Connecteurs & sources | |
| 89 | + | |
| 90 | +**105 connecteurs enregistrés** (paquet `immoka/connectors/`), un par source, orchestrés par la boucle d'ingestion : | |
| 91 | + | |
| 92 | +| Famille de sources | Exemples | Technique d'extraction | | |
| 93 | +|---|---|---| | |
| 94 | +| Flux centraux de bannières | RE/MAX Québec, Royal LePage, Sutton, Via Capitale, Century 21, Proprio Direct | API JSON internes (Meilisearch, Algolia, source.immo, wp-json) | | |
| 95 | +| 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 | | |
| 96 | +| Sans courtier / petites annonces | DuProprio, Kijiji, LesPAC, Facebook Marketplace | API publiques + extraction dédiée | | |
| 97 | +| Sites vitrines & SPA anti-bot | agences boutique (Charisma, Imcha, Immeubles Stuart…), GuideHabitation | JSON-LD génériques, sitemaps, Firecrawl en secours | | |
| 98 | + | |
| 99 | +- **Normalisation** : chaque annonce est projetée vers le schéma unique `PropertyListing` (`immoka/schema.py`). | |
| 100 | +- **Dédup** : par numéro Centris (`dup_hidden`) — une propriété affichée par 3 sites = 1 fiche, sources créditées. | |
| 101 | +- **Détection de changements** : upsert par **hash de contenu** ; retraits avec **délai de grâce** contre les ratés ponctuels d'un site. | |
| 102 | +- **Qualité** : couche `quality.py` + `imgaudit.py` — annonces publiées vs **quarantaine**, audit des images, golden record. | |
| 103 | +- **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. | |
| 104 | + | |
| 41 | 105 | ## Architecture |
| 42 | 106 | |
| 43 | 107 | | Composant | Rôle | |
@@ -68,6 +132,12 @@ Les sites d'agences n'offrent pas de webhooks : Immo-Ka en reproduit l'équivale | ||
| 68 | 132 | | `scripts/` | outillage (génération des docs connecteurs, rafraîchissement Via Capitale, validation du rendu) | |
| 69 | 133 | | `run.py` / `requirements.txt` | point d'entrée CLI (`sync`, `watch`, `serve`, `list`, `geocode`, `poi`, `quartier`, …) et dépendances backend | |
| 70 | 134 | |
| 135 | +## Documentation | |
| 136 | + | |
| 137 | +- **Guide d'utilisation en ligne** : [www.immo-ka.com/doc/](https://www.immo-ka.com/doc/) — visite pas à pas du site (accueil, recherche filtrée, fiche détail, carte), avec captures annotées. | |
| 138 | +- **Guide PDF téléchargeable** : [immo-ka-documentation.pdf](https://www.immo-ka.com/doc/immo-ka-documentation.pdf) — la même documentation, mise en page aux couleurs du site. | |
| 139 | +- Les captures du guide sont versionnées dans `frontend/public/doc/img/` (servies telles quelles par le site). | |
| 140 | + | |
| 71 | 141 | ## Développement (remote-first) |
| 72 | 142 | |
| 73 | 143 | La **source de vérité est le repo git sur le nœud M4M64a** (`~/apps/immo-ka`) — immo-ka n'a **aucune copie laptop**. Toute modification se fait sur le nœud via SSH : édition, build, redémarrage, puis commit/push depuis le nœud (agent forwarding actif). |
@@ -101,19 +171,26 @@ En production sur le **nœud M4M64a** du cluster MacLustr (`~/apps/immo-ka`), se | ||
| 101 | 171 | |
| 102 | 172 | ## Écosystème Groupe KA |
| 103 | 173 | |
| 104 | −- [groupe-ka.com](https://www.groupe-ka.com) — portail | |
| 105 | −- [lou-ka.com](https://www.lou-ka.com) — logements à louer | |
| 106 | −- [immo-ka.com](https://www.immo-ka.com) — propriétés à vendre | |
| 107 | −- [vrai-prix.com](https://www.vrai-prix.com) — estimation immobilière | |
| 108 | −- [auto-ka.com](https://www.auto-ka.com) — véhicules | |
| 109 | −- [fabri-ka.com](https://www.fabri-ka.com) — produits québécois | |
| 110 | −- [food-ka.com](https://www.food-ka.com) — épicerie/alimentation | |
| 111 | −- [resto-ka.com](https://www.resto-ka.com) — restaurants | |
| 112 | −- [sorti-ka.com](https://www.sorti-ka.com) — sorties et événements | |
| 113 | −- [job-ka.com](https://www.job-ka.com) — emplois | |
| 114 | −- [crea-ka.com](https://www.crea-ka.com) — créateurs | |
| 115 | −- [trouve-ka.com](https://www.trouve-ka.com) — petites annonces | |
| 116 | −- [api-ka.com](https://www.api-ka.com) — API de données | |
| 174 | +| Plateforme | Univers | | |
| 175 | +|---|---| | |
| 176 | +| [groupe-ka.com](https://www.groupe-ka.com) | portail & KA ID | | |
| 177 | +| [lou-ka.com](https://www.lou-ka.com) | logements à louer | | |
| 178 | +| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre | | |
| 179 | +| [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière | | |
| 180 | +| [auto-ka.com](https://www.auto-ka.com) | véhicules | | |
| 181 | +| [fabri-ka.com](https://www.fabri-ka.com) | produits québécois | | |
| 182 | +| [food-ka.com](https://www.food-ka.com) | épicerie/alimentation | | |
| 183 | +| [resto-ka.com](https://www.resto-ka.com) | restaurants | | |
| 184 | +| [sorti-ka.com](https://www.sorti-ka.com) | sorties et événements | | |
| 185 | +| [job-ka.com](https://www.job-ka.com) | emplois | | |
| 186 | +| [crea-ka.com](https://www.crea-ka.com) | créateurs | | |
| 187 | +| [trouve-ka.com](https://www.trouve-ka.com) | petites annonces | | |
| 188 | +| [api-ka.com](https://www.api-ka.com) | API de données | | |
| 189 | + | |
| 190 | +## Contact | |
| 191 | + | |
| 192 | +**Simon-Pierre Boucher** — fondateur, Groupe KA | |
| 193 | +📧 [contact@spboucher.ai](mailto:contact@spboucher.ai) | |
| 117 | 194 | |
| 118 | 195 | --- |
| 119 | 196 | |
| 120 | 197 | |