docs: README v3 — chiffres live vérifiés, pastilles dynamiques, sections complètes
1 changed file +110 −44
modified
README.md
+110 −44
@@ -14,11 +14,26 @@ | ||
| 14 | 14 |  |
| 15 | 15 |  |
| 16 | 16 |  |
| 17 | − | |
| 17 | + | |
| 18 | +[](https://www.vrai-prix.com/api/stats) | |
| 19 | +[](https://www.vrai-prix.com/api/stats) | |
| 20 | +[](https://www.vrai-prix.com/api/stats) | |
| 21 | +[](https://www.vrai-prix.com/api/stats) | |
| 22 | +[](https://www.vrai-prix.com/api/stats) | |
| 23 | +[](https://www.vrai-prix.com/api/stats) | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 18 | 28 |  |
| 19 | − | |
| 20 | 29 |  |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 21 | 35 |  |
| 36 | + | |
| 22 | 37 | |
| 23 | 38 | </div> |
| 24 | 39 | |
@@ -26,6 +41,21 @@ Vrai-Prix estime la valeur marchande de **n'importe quelle propriété du Québe | ||
| 26 | 41 | |
| 27 | 42 | Sous le capot : les **6 millésimes (2021-2026)** des rôles d'évaluation foncière géoréférencés du Québec (**MAMH**, données ouvertes) — **3 747 008 propriétés**, soit **22 150 285 observations** — fusionnés spatialement avec **745 119 transactions réelles** (99,88 % d'appariement, distance médiane 0,6 m), alimentant un **modèle hédonique LightGBM** (MdAPE 11,0 %, ratio médian 0,995 en holdout) et un **moteur de comparables ajustés**. Pour qui ? Propriétaires, acheteurs, courtiers et curieux qui veulent une estimation honnête et vérifiable, gratuite, sur les **1 097 municipalités** de la province. |
| 28 | 43 | |
| 44 | +## Chiffres clés (live sur [/api/stats](https://www.vrai-prix.com/api/stats), vérifiés au 2026-08-24) | |
| 45 | + | |
| 46 | +| Métrique | Valeur | | |
| 47 | +|---|---| | |
| 48 | +| Propriétés (unités d'évaluation) | **3 747 008** | | |
| 49 | +| Observations (6 millésimes 2021-2026) | **22 150 285** | | |
| 50 | +| Transactions réelles appariées | **745 119** (99,88 %, distance médiane 0,6 m) | | |
| 51 | +| Logements couverts | **4 400 551** | | |
| 52 | +| Municipalités | **1 097** | | |
| 53 | +| Valeur totale du parc 2026 | **2 009 452 277 400 $** (≈ 2,01 billions $) | | |
| 54 | +| Valeur médiane 2026 | **444 300 $** | | |
| 55 | +| Croissance 2021 → 2026 | **+43,1 %** | | |
| 56 | +| Modèle | hédonique LightGBM + comparables ajustés — **MdAPE 11,0 %**, ratio médian 0,995 | | |
| 57 | +| Millésime de la base | 2026 (dernier recalcul : 2026-08-08) | | |
| 58 | + | |
| 29 | 59 | ## Visite guidée |
| 30 | 60 | |
| 31 | 61 | <table> |
@@ -73,10 +103,11 @@ Sous le capot : les **6 millésimes (2021-2026)** des rôles d'évaluation fonci | ||
| 73 | 103 | - **Estimation hybride** — 65 % modèle hédonique LightGBM + 35 % comparables ajustés (marché, superficie, âge), fourchette P10–P90 par régression quantile, indice de confiance A–D obligatoire. |
| 74 | 104 | - **Portrait de la propriété** — façade SVG dessinée par les données du registre, terrain à l'échelle, composition de la valeur ; historique 2021→2026 (six millésimes, badges YoY). |
| 75 | 105 | - **Vrai-Prix Maps** — recherche par carte 3D (Mapbox GL via le framework partagé `@groupe-ka/ka-maps`), grappes de valeurs estimées pilotées par le viewport ; plan des comparables « arpenteur » en SVG pur. |
| 76 | −- **Ka · agent IA** — agent conversationnel (Claude, SDK Anthropic, streaming SSE) branché sur **12 outils serveur** : évaluation, comparables, stats, dossier d'expert, parc immobilier. | |
| 106 | +- **Ka · agent IA** — agent conversationnel (Claude, SDK Anthropic, streaming SSE) branché sur **12 outils serveur** : `evaluer_propriete`, `chercher_propriete`, `chercher_proprietes_secteur`, `comparables_detailles`, `comparer_proprietes`, `estimation_manuelle`, `evaluer_parc`, `dossier_complet`, `indice_marche`, `stats_municipalite`, `stats_provinciales`, `liens_rapports`. | |
| 77 | 107 | - **Rapports PDF 100 % vectoriels** (pdfkit) — standard (3 p.), professionnel bancaire (6 p.), parc consolidé, statistique provincial. |
| 78 | 108 | - **Parc immobilier** — évaluation multi-adresses agrégée (jusqu'à 40 propriétés). |
| 79 | −- **Statistiques provinciales** — valeur totale du parc (2,01 billions $), palmarès des 200 municipalités, tableau de bord `/stats` + rapports PDF v3. | |
| 109 | +- **Statistiques provinciales** — valeur totale du parc (2,01 billions $ au millésime 2026), palmarès des 200 municipalités, tableau de bord `/stats` + rapports PDF v3 personnalisés (catalogue de blocs, ReportBuilder). | |
| 110 | +- **Contexte marché** — indice de marché, fourchette visuelle, accueil enrichi (upgrade 2026-08-22). | |
| 80 | 111 | - **SEO programmatique — 3,76 M d'URLs indexables** : 1 097 pages municipalités + ~5 900 pages municipalité × type + 3,75 M fiches d'estimation SSR avec métadonnées uniques, JSON-LD, sitemaps générés à la volée. |
| 81 | 112 | - **KA ID** — connexion unique du Groupe KA (SSO signé via le hub groupe-ka.com, sans base d'utilisateurs) + favoris « Mon univers Ka ». |
| 82 | 113 | - **Bilingue FR/EN**, méthodologie publique (7 sections, IAAO), conformité Loi 25, app compagnon iOS SwiftUI (dépôt séparé). |
@@ -96,35 +127,47 @@ Application Next.js 16 (App Router) — SQLite better-sqlite3 (units + FTS5 | ||
| 96 | 127 | · SSO KA ID · SEO programmatique |
| 97 | 128 | ``` |
| 98 | 129 | |
| 99 | −- **Frontend / API** : Next.js 16, TypeScript strict, Tailwind CSS 4 — tout est servi par une seule app (pages SSR + routes `/api/*`). | |
| 100 | −- **Base de données** : SQLite (`data/vraiprix.db`, ~1,5 Go, non versionnée) — 3,75 M unités, FTS5, index spatiaux, mode WAL. | |
| 101 | −- **Modèle** : pipeline externe LightGBM / scikit-learn (réentraînement : `scripts/hedonic-retrain.py`), estimations pré-calculées injectées dans la base. | |
| 102 | −- **Tests** : Vitest (moteur d'estimation) + Playwright (captures : `scripts/screenshots.mjs`). | |
| 103 | − | |
| 104 | −## API — endpoints principaux | |
| 105 | − | |
| 106 | −| Endpoint | Rôle | | |
| 107 | −|---|---| | |
| 108 | −| `GET /api/search` | recherche plein-texte d'adresses (FTS5, tolérante aux fautes) | | |
| 109 | −| `GET /api/estimate` | estimation hybride d'une unité (modèle + comparables, P10–P90, confiance A–D) | | |
| 110 | −| `GET /api/nearby` | unités voisines / grappes pour la carte | | |
| 111 | −| `POST /api/ka` | agent Ka (Claude, streaming SSE, 12 outils serveur) | | |
| 112 | −| `POST /api/portfolio` | évaluation de parc immobilier multi-adresses (≤ 40) | | |
| 113 | −| `GET /api/report` · `/api/report/pro` · `/api/report/portfolio` · `/api/report/stats` | rapports PDF vectoriels (standard, bancaire, parc, provincial) | | |
| 114 | −| `GET /api/stats` · `/api/stats/catalog` · `/api/stats/dashboard` · `/api/stats/report(/custom)` | statistiques provinciales + kit de rapports v3 | | |
| 115 | −| `/api/auth/ka/*` · `/api/auth/me` · `/api/auth/logout` | SSO KA ID (hub groupe-ka.com) | | |
| 116 | −| `GET /api/favorites` · `POST /api/favorites/toggle` | favoris « Mon univers Ka » | | |
| 117 | −| `POST /api/lead` | prise de contact / lead | | |
| 118 | − | |
| 119 | −## Données & sources | |
| 130 | +- **Frontend / API** : Next.js **16.3** (App Router), React **19**, TypeScript strict, Tailwind CSS **4** — tout est servi par une seule app (pages SSR + routes `/api/*`). | |
| 131 | +- **Base de données** : SQLite (`data/vraiprix.db`, ~1,5 Go, non versionnée) via **better-sqlite3** — 3,75 M unités, FTS5, index spatiaux, mode WAL. | |
| 132 | +- **Modèle** : pipeline externe LightGBM / scikit-learn (réentraînement : `scripts/hedonic-retrain.py`), estimations pré-calculées injectées dans la base (dernière ré-estimation sur le nœud : 2026-08-22, terrain/autre + recalibrage P10/P90). | |
| 133 | +- **Agent Ka** : SDK Anthropic (`@anthropic-ai/sdk`), streaming SSE, 12 outils serveur, garde anti-hallucination sur les liens PDF. | |
| 134 | +- **PDF** : pdfkit (rapports 100 % vectoriels, aucune capture d'écran). | |
| 135 | +- **Tests** : Vitest (moteur d'estimation, `npm run test`) + Playwright (captures : `scripts/screenshots.mjs`). | |
| 136 | + | |
| 137 | +## API — endpoints principaux (21 routes) | |
| 138 | + | |
| 139 | +| Endpoint | Méthode | Rôle | | |
| 140 | +|---|---|---| | |
| 141 | +| `/api/search` | GET | recherche plein-texte d'adresses (FTS5, tolérante aux fautes) | | |
| 142 | +| `/api/estimate` | GET | estimation hybride d'une unité (modèle + comparables, P10–P90, confiance A–D) | | |
| 143 | +| `/api/nearby` | GET | unités voisines / grappes pour la carte | | |
| 144 | +| `/api/ka` | POST | agent Ka (Claude, streaming SSE, 12 outils serveur) | | |
| 145 | +| `/api/portfolio` | POST | évaluation de parc immobilier multi-adresses (≤ 40) | | |
| 146 | +| `/api/report` | GET | rapport PDF standard (3 p.) | | |
| 147 | +| `/api/report/pro` | GET | rapport PDF professionnel bancaire (6 p.) | | |
| 148 | +| `/api/report/portfolio` | GET | rapport PDF de parc consolidé | | |
| 149 | +| `/api/report/stats` | GET | rapport PDF statistique provincial | | |
| 150 | +| `/api/stats` | GET | agrégats provinciaux publics (source des pastilles dynamiques ci-dessus) | | |
| 151 | +| `/api/stats/catalog` · `/api/stats/dashboard` | GET | catalogue de blocs + tableau de bord (kit stats v3 Groupe KA) | | |
| 152 | +| `/api/stats/report` · `/api/stats/report/custom` | GET/POST | rapports PDF v3 (modèles + personnalisés) | | |
| 153 | +| `/api/auth/ka/login` · `/api/auth/ka/callback` | GET | SSO KA ID (hub groupe-ka.com) | | |
| 154 | +| `/api/auth/me` · `/api/auth/logout` | GET/POST | session KA ID | | |
| 155 | +| `/api/favorites` · `/api/favorites/toggle` | GET/POST | favoris « Mon univers Ka » | | |
| 156 | +| `/api/lead` | POST | prise de contact / lead | | |
| 157 | + | |
| 158 | +## Données & conformité | |
| 120 | 159 | |
| 121 | 160 | | Source | Contenu | Volume | Mise à jour | |
| 122 | 161 | |---|---|---|---| |
| 123 | −| **MAMH — rôles d'évaluation foncière géoréférencés** (données ouvertes) | 6 millésimes 2021-2026, caractéristiques complètes des unités | 3 747 008 propriétés · 22 150 285 observations | à chaque millésime annuel (réingestion `scripts/`) | | |
| 162 | +| **MAMH — rôles d'évaluation foncière géoréférencés** (données ouvertes, Données Québec) | 6 millésimes 2021-2026, caractéristiques complètes des unités | 3 747 008 propriétés · 22 150 285 observations | à chaque millésime annuel (réingestion `scripts/`) | | |
| 124 | 163 | | **Transactions réelles** (fusion spatiale XY, EPSG:32198) | prix de vente appariés aux unités (99,88 %, distance médiane 0,6 m) | 745 119 transactions | lors du réentraînement du modèle | |
| 164 | +| **Connecteur « nouvelles ventes »** (JdM / api.qub.ca) | ingestion incrémentale de transactions récentes | à la demande | `scripts/ingest-jdm.mjs` (process PM2 `vrai-prix-ingest`) | | |
| 125 | 165 | | **Modèle hédonique LightGBM** | log-prix, 18 variables, quantiles P10/P90 — MdAPE 11,0 %, ratio médian 0,995 | estimations pré-calculées sur ~3,75 M unités | réentraînement `scripts/hedonic-retrain.py` (hors ligne) | |
| 126 | 166 | |
| 127 | −Contrairement aux apps à connecteurs du Groupe KA, Vrai-Prix ne dépend d'aucune synchronisation horaire : la base est **pré-calculée** et versionnée par millésime — l'app sert les estimations en lecture seule. | |
| 167 | +- Contrairement aux apps à connecteurs du Groupe KA, Vrai-Prix ne dépend d'aucune synchronisation horaire : la base est **pré-calculée** et versionnée par millésime — l'app sert les estimations en lecture seule. | |
| 168 | +- **Méthodologie publique** (7 sections, normes IAAO) publiée intégralement sur le site ; chaque estimation affiche ses comparables, ses ajustements et son indice de confiance. | |
| 169 | +- **Disclaimer** : estimations statistiques à titre indicatif — elles ne remplacent pas une évaluation par un évaluateur agréé (**OEAQ**). | |
| 170 | +- **Vie privée** : conformité Loi 25 ; SSO KA ID sans base d'utilisateurs locale ; analytics première partie (admin-ka `/collect`), aucun script publicitaire (Monetag retiré le 2026-08-23). | |
| 128 | 171 | |
| 129 | 172 | ## Structure du repo |
| 130 | 173 | |
@@ -132,14 +175,26 @@ Contrairement aux apps à connecteurs du Groupe KA, Vrai-Prix ne dépend d'aucun | ||
| 132 | 175 | |---|---| |
| 133 | 176 | | `src/app/` | pages App Router (accueil, `estimation/[id]`, `municipalite/[slug]/[type]`, `carte`, `ka`, `parc`, `stats`, `favoris`, sitemaps/robots) + routes `/api/*` | |
| 134 | 177 | | `src/components/` | SearchBox, ResultView, MetricViz, RadarMap, KaCarte, KaChat, StatsView… | |
| 135 | −| `src/lib/` | moteur de comparables (`engine.ts`), accès DB, agrégats municipalités, agent Ka, SSO KA ID, générateurs PDF | | |
| 178 | +| `src/lib/` | moteur de comparables (`engine.ts`), accès DB, agrégats municipalités, agent Ka (`ka/`), SSO KA ID, générateurs PDF (`report*.ts`), SEO, i18n | | |
| 136 | 179 | | `data/` | base SQLite `vraiprix.db` (non versionnée) | |
| 137 | −| `scripts/` | réentraînement hédonique, build des stats, ingestion, captures Playwright | | |
| 138 | −| `docs/` | pipeline de données, notes Ka Maps, captures d'écran | | |
| 180 | +| `scripts/` | réentraînement hédonique, build des stats, ingestion (dont `ingest-jdm.mjs`), captures Playwright | | |
| 181 | +| `docs/` | pipeline de données (`PIPELINE-DONNEES.md`), notes Ka Maps, captures d'écran | | |
| 139 | 182 | | `public/` | assets statiques (favicons, OG, polices) + guide `/doc` (page, images, PDF) | |
| 140 | 183 | | `ios/` | ressources de l'app compagnon iOS (SwiftUI) | |
| 141 | 184 | | `assets/` | matériel graphique du projet | |
| 142 | 185 | |
| 186 | +## Démarrage rapide | |
| 187 | + | |
| 188 | +```bash | |
| 189 | +ssh M3U96a && cd ~/apps/vrai-prix | |
| 190 | +npm install # dépendances (au besoin) | |
| 191 | +npm run test # Vitest — moteur d'estimation (src/lib/engine.test.ts) | |
| 192 | +npm run lint # ESLint 9 + config Next | |
| 193 | +npm run dev # serveur de développement (next dev) | |
| 194 | +npm run build # build de production | |
| 195 | +npm start # next start (en prod : PM2, voir Déploiement) | |
| 196 | +``` | |
| 197 | + | |
| 143 | 198 | ## Développement (remote-first) |
| 144 | 199 | |
| 145 | 200 | ⚠️ **La source de vérité est le repo git sur le nœud M3U96a** (`~/apps/vrai-prix`) — on n'édite **jamais** les copies laptop. Toute modification se fait sur le nœud via SSH : édition, build, redémarrage, puis commit + push **depuis le nœud**. |
@@ -148,25 +203,24 @@ Contrairement aux apps à connecteurs du Groupe KA, Vrai-Prix ne dépend d'aucun | ||
| 148 | 203 | - remote secondaire `github` → github.com/spboucher-ai/vrai-prix. |
| 149 | 204 | |
| 150 | 205 | ```bash |
| 151 | −ssh M3U96a | |
| 152 | 206 | cd ~/apps/vrai-prix |
| 153 | −npm install # au besoin | |
| 154 | −npm run test # Vitest — moteur d'estimation | |
| 155 | −npm run dev # développement | |
| 156 | −npm run build # build de production | |
| 157 | −pm2 restart vrai-prix # après changement | |
| 207 | +npm run build # après changement de code | |
| 208 | +pm2 restart vrai-prix | |
| 158 | 209 | git add <fichiers> && git commit -m "…" && git push origin main |
| 159 | 210 | ``` |
| 160 | 211 | |
| 161 | −### Configuration notable (sans secrets) | |
| 212 | +## Variables d'environnement | |
| 213 | + | |
| 214 | +Noms seulement — **aucun secret n'est versionné** (`.env.local` sur le nœud). | |
| 162 | 215 | |
| 163 | 216 | | Variable | Rôle | |
| 164 | 217 | |---|---| |
| 165 | 218 | | `VRAIPRIX_DB` | chemin de la base SQLite (`data/vraiprix.db`) | |
| 166 | 219 | | `NEXT_PUBLIC_SITE_URL` | URL canonique du site (SEO, sitemaps) | |
| 220 | +| `NEXT_PUBLIC_MAPBOX_TOKEN` | carte 3D Vrai-Prix Maps (jeton public) | | |
| 167 | 221 | | `ANTHROPIC_API_KEY` | agent Ka (Claude) | |
| 168 | −| `NEXT_PUBLIC_MAPBOX_TOKEN` | carte 3D Vrai-Prix Maps | | |
| 169 | −| `KA_SSO_SECRET` · `KA_AUTH_SECRET` · `KA_HUB_URL` · `KA_BASE_URL` | SSO KA ID (hub groupe-ka.com) | | |
| 222 | +| `KA_SSO_SECRET` · `KA_AUTH_SECRET` | signature SSO / session KA ID | | |
| 223 | +| `KA_HUB_URL` · `KA_BASE_URL` | hub groupe-ka.com + URL de rappel du site | | |
| 170 | 224 | |
| 171 | 225 | ## Déploiement |
| 172 | 226 | |
@@ -176,10 +230,11 @@ git add <fichiers> && git commit -m "…" && git push origin main | ||
| 176 | 230 | | **Port** | **8090** | |
| 177 | 231 | | **Domaine** | [www.vrai-prix.com](https://www.vrai-prix.com) via tunnel ngrok | |
| 178 | 232 | |
| 179 | −| Processus PM2 | Rôle | | |
| 180 | −|---|---| | |
| 181 | −| `vrai-prix` | l'app Next.js (`next start -H 0.0.0.0 -p 8090`) — pages SSR + API | | |
| 182 | −| `vrai-prix-ngrok` | tunnel ngrok vers www.vrai-prix.com | | |
| 233 | +| Processus PM2 | Commande réelle | Rôle | | |
| 234 | +|---|---|---| | |
| 235 | +| `vrai-prix` | `next start -H 0.0.0.0 -p 8090` | l'app Next.js — pages SSR + API | | |
| 236 | +| `vrai-prix-ngrok` | `ngrok http --url=www.vrai-prix.com 8090` | tunnel vers www.vrai-prix.com | | |
| 237 | +| `vrai-prix-ingest` | `node scripts/ingest-jdm.mjs` | connecteur incrémental « nouvelles ventes » — lancé à la demande, arrêté au repos | | |
| 183 | 238 | |
| 184 | 239 | ```bash |
| 185 | 240 | # sur M3U96a, après un changement : |
@@ -192,7 +247,18 @@ pm2 logs vrai-prix --lines 30 | ||
| 192 | 247 | - **Guide utilisateur en ligne** : [www.vrai-prix.com/doc/index.html](https://www.vrai-prix.com/doc/index.html) — à quoi sert le site, utilisation en 5 étapes, provenance des données, FAQ. |
| 193 | 248 | - **Guide PDF téléchargeable** : [vrai-prix-documentation.pdf](https://www.vrai-prix.com/doc/vrai-prix-documentation.pdf). |
| 194 | 249 | - **Méthodologie complète** (normes IAAO, 7 sections) : publiée sur le site. |
| 195 | −- **Docs internes** : `docs/` (pipeline de données, notes Ka Maps, captures). | |
| 250 | +- **Docs internes** : `docs/` (pipeline de données `PIPELINE-DONNEES.md`, notes Ka Maps, captures). | |
| 251 | + | |
| 252 | +## Historique | |
| 253 | + | |
| 254 | +| Date | Jalon | | |
| 255 | +|---|---| | |
| 256 | +| 2026-08-08 | naissance du projet ; 08-09 : moteur d'évaluation transparent v1 + agent Ka (Claude, streaming, 11 puis 12 outils) | | |
| 257 | +| 2026-08-13 | Vrai-Prix Maps (framework Ka Maps), SSO KA ID, SEO programmatique (sitemaps 3,7 M de fiches) | | |
| 258 | +| 2026-08-17 | harmonisation Groupe KA (ka-ui, footer commun) + API publique `/api/stats` + assets OG | | |
| 259 | +| 2026-08-19 | stats v2 (`/stats` ultra complet + 5 rapports PDF), KA Agent v2 plein écran, socle mobile | | |
| 260 | +| 2026-08-22 | ré-estimation hédonique sur le nœud (terrain/autre + recalibrage P10/P90), connecteur « nouvelles ventes » JdM, upgrade apparence (contexte marché, fourchette visuelle) | | |
| 261 | +| 2026-08-23/24 | stats v3 (rapports PDF personnalisés), favoris « Mon univers Ka », page `/doc` + PDF, README v3 | | |
| 196 | 262 | |
| 197 | 263 | ## Écosystème Groupe KA |
| 198 | 264 | |
| 199 | 265 | |