docs: README — méthode du coût, propriétés à vendre, routes API, variables, processus PM2 (immoka-sync, cost-sync), historique 2026-09-08
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
1 changed file +29 −5
modified
README.md
+29 −5
@@ -198,6 +198,8 @@ Sous le capot : les **6 millésimes (2021-2026)** des rôles d'évaluation fonci | ||
| 198 | 198 | - **Parc immobilier** — évaluation multi-adresses agrégée (jusqu'à 40 propriétés). |
| 199 | 199 | - **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). |
| 200 | 200 | - **Contexte marché** — indice de marché, fourchette visuelle, accueil enrichi (upgrade 2026-08-22). |
| 201 | +- **Méthode du coût — [`/cout`](https://www.vrai-prix.com/cout)** (2026-09-08) — la troisième lecture de la valeur : coût de remplacement à neuf décomposé par **assemblages** (≈ 100 assemblages, ≈ 550 composants, 184 articles), matériaux sourcés chez les détaillants publics (Canac, BMR, Patrick Morin — médiane robuste multi-source, aberrations marquées), heures de métier aux **taux employeur complets APCHQ/CCQ** (2 895 grilles 2023→2026), indices **StatCan 18-10-0289-01**, facteurs régionaux (16 localisations), indirects / frais généraux / profit / contingence, **dépréciation** âge-vie ou par composante, valeur du terrain (rôle, saisie, résiduel), fourchette P10-P90 et confiance A-D décomposée ; atelier propriété (préremplissage du rôle) ou construction, catalogue d'assemblages, mode exercice, PDF « Rapport — Méthode du coût » (9 p.), console admin des connecteurs, 9 outils Ka `cout_*`. Chaque nombre porte sa provenance (● observé · ◐ calculé · ○ indexé · ◇ hypothèse) et chaque estimation est reproductible (instantané des prix). | |
| 202 | +- **Propriétés à vendre — [`/a-vendre`](https://www.vrai-prix.com/a-vendre)** (2026-09-08) — toutes les propriétés réellement à vendre au Québec (copie nocturne de la base **Immo-Ka**, ≈ 71 000 annonces vivantes), chacune jumelée spatialement à son unité du rôle et **déjà mesurée par le moteur** (≈ 66 000) : recherche FTS + filtres, fiche complète (galerie, prix, caractéristiques, historique de prix, mesure vs prix demandé, duel des méthodes, portrait au rôle, voisines), **atelier « mon évaluation »** (bassin de ventes réelles et d'annonces, choix des comparables, grille d'ajustements en $ pré-remplie, réconciliation, confrontation — localStorage), **analyse IA du bâtiment** (Claude Sonnet 5 lit photos + description → composantes avec confiance et provenance → moteur déterministe du coût ; corrections manuelles, JSON technique, similaires techniques) ; [`/stats/marche`](https://www.vrai-prix.com/stats/marche) publie la mesure à l'épreuve du marché (ratio, MdAPE, calibration A-D, méthodes). | |
| 201 | 203 | - **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. |
| 202 | 204 | - **KA ID** — connexion unique du Groupe KA (SSO signé via le hub groupe-ka.com, sans base d'utilisateurs) + favoris « Mon univers Ka ». |
| 203 | 205 | - **Bilingue FR/EN**, méthodologie publique (7 sections, IAAO), conformité Loi 25, app compagnon iOS SwiftUI (dépôt séparé). |
@@ -224,10 +226,17 @@ Application Next.js 16 (App Router) — SQLite better-sqlite3 (units + FTS5 | ||
| 224 | 226 | - **PDF** : pdfkit (rapports 100 % vectoriels, aucune capture d'écran). |
| 225 | 227 | - **Tests** : Vitest (moteur d'estimation, `npm run test`) + Playwright (captures : `scripts/screenshots.mjs`). |
| 226 | 228 | |
| 227 | −## API — endpoints principaux (21 routes) | |
| 229 | +## API — endpoints principaux (21 routes + 29 routes coût / annonces) | |
| 228 | 230 | |
| 229 | 231 | | Endpoint | Méthode | Rôle | |
| 230 | 232 | |---|---|---| |
| 233 | +| `/api/cost/overview` · `/items` · `/items/[code]` · `/assemblies` · `/assemblies/[code]` · `/labour` · `/locations` · `/materials/history` · `/benchmarks` · `/sources` | GET | base de coûts (lecture seule, cache 10 min) | | |
| 234 | +| `/api/cost/property?id=` | GET | préremplissage d'une propriété du rôle + autres lectures de la valeur | | |
| 235 | +| `/api/cost/estimate` · `/estimate/[id]` | POST · GET | calcul déterministe (sauvegardé avec instantané des prix) · relecture | | |
| 236 | +| `/api/cost/report?estimate=` | GET · POST | PDF « Rapport — Méthode du coût » | | |
| 237 | +| `/api/admin/cost/*` | GET · POST | connecteurs, synchro, anomalies, correspondances, imports, usage IA — jeton `COST_ADMIN_TOKEN` | | |
| 238 | +| `/api/avendre` · `/api/avendre/comps` | GET | recherche d'annonces (FTS, facettes, tris) · bassin de comparables d'une annonce | | |
| 239 | +| `/api/listings/[uid]/ai-cost-analysis` (+ `/reanalyze`, `/override`) · `/cost-estimate` · `/technical-similar` · `/ai-analysis-json` | POST · GET · PATCH | analyse IA du bâtiment (à la demande, quotas 3 / 10 min / IP, 30 / jour, budget), recalcul aux coûts du jour, similaires techniques, export JSON | | |
| 231 | 240 | | `/api/search` | GET | recherche plein-texte d'adresses (FTS5, tolérante aux fautes) | |
| 232 | 241 | | `/api/estimate` | GET | estimation hybride d'une unité (modèle + comparables, P10–P90, confiance A–D) | |
| 233 | 242 | | `/api/nearby` | GET | unités voisines / grappes pour la carte | |
@@ -265,10 +274,12 @@ Application Next.js 16 (App Router) — SQLite better-sqlite3 (units + FTS5 | ||
| 265 | 274 | |---|---| |
| 266 | 275 | | `src/app/` | pages App Router (accueil, `estimation/[id]`, `municipalite/[slug]/[type]`, `carte`, `ka`, `parc`, `stats`, `favoris`, sitemaps/robots) + routes `/api/*` | |
| 267 | 276 | | `src/components/` | SearchBox, ResultView, MetricViz, RadarMap, KaCarte, KaChat, StatsView… | |
| 268 | −| `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 | | |
| 269 | −| `data/` | base SQLite `vraiprix.db` (non versionnée) | | |
| 270 | −| `scripts/` | réentraînement hédonique, build des stats, ingestion (dont `ingest-jdm.mjs`), captures Playwright | | |
| 271 | −| `docs/` | pipeline de données (`PIPELINE-DONNEES.md`), notes Ka Maps, captures d'écran (`screenshots/` : visite guidée 10 pages + manifeste, galeries WebP mobile/desktop ; `archive/` : captures v1) | | |
| 277 | +| `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 ; **`cost/`** (méthode du coût : `types` · `taxonomy` · `units` · `geometry` · `pricing` · `engine` · `catalog` · `estimate` · `db` · `seed/` · `connectors/` · `ai/`) ; **`immoka.ts`** (annonces, FTS, `vp_eval`), `comps.ts` (bassin de comparables), `listing-types.ts`, `marche-stats.ts`, `report-cost.ts` | | |
| 278 | +| `src/components/cout/`, `src/components/avendre/` | atelier de la méthode du coût (Landing, Workbench, panneaux, graphiques SVG, admin) ; fiche d'annonce, atelier d'évaluation, analyse IA | | |
| 279 | +| `data/` | bases SQLite non versionnées : `vraiprix.db` (rôle + ventes), `immoka.db` (copie Immo-Ka rafraîchie chaque nuit, table `vp_eval`), `cost.db` (base de coûts, s'auto-crée depuis les seeds), `marche-stats.json` (agrégats nocturnes) | | |
| 280 | +| `prompts/` | prompt système de l'analyse IA du bâtiment (`property-cost-analysis-v1.md`, versionné par `PROMPT_VERSION`) | | |
| 281 | +| `scripts/` | réentraînement hédonique, build des stats, ingestion (dont `ingest-jdm.mjs`), captures Playwright ; **`immoka-sync.sh`** (snapshot Immo-Ka → ré-évaluation en shards → `vp_eval` → bascule), `eval-immoka.ts` + `run-eval-shards.sh`, `build-marche-stats.mjs`, `cost-sync.ts` (connecteurs de la base de coûts) | | |
| 282 | +| `docs/` | pipeline de données (`PIPELINE-DONNEES.md`), **méthode du coût** (`cost-method-implementation-plan.md`, `cost-connectors.md`), notes Ka Maps, captures d'écran (`screenshots/` : visite guidée 10 pages + manifeste, galeries WebP mobile/desktop ; `archive/` : captures v1) | | |
| 272 | 283 | | `public/` | assets statiques (favicons, OG, polices) + guide `/doc` (page, images, PDF) | |
| 273 | 284 | | `ios/` | ressources de l'app compagnon iOS (SwiftUI) | |
| 274 | 285 | | `assets/` | matériel graphique du projet | |
@@ -311,6 +322,11 @@ Noms seulement — **aucun secret n'est versionné** (`.env.local` sur le nœud) | ||
| 311 | 322 | | `ANTHROPIC_API_KEY` | agent Ka (Claude) | |
| 312 | 323 | | `KA_SSO_SECRET` · `KA_AUTH_SECRET` | signature SSO / session KA ID | |
| 313 | 324 | | `KA_HUB_URL` · `KA_BASE_URL` | hub groupe-ka.com + URL de rappel du site | |
| 325 | +| `IMMOKA_DB` · `COST_DB` | chemins des bases `immoka.db` (copie Immo-Ka, **doit exister**) et `cost.db` (s'auto-crée) | | |
| 326 | +| `COST_ADMIN_TOKEN` | jeton Bearer des routes `/api/admin/cost/*` (503 si absent) | | |
| 327 | +| `FIRECRAWL_API_KEY` | connecteurs de la base de coûts (`npm run cost:sync`, jamais dans le chemin utilisateur) | | |
| 328 | +| `PROPERTY_ANALYSIS_MODEL` · `PROPERTY_ANALYSIS_MAX_IMAGES` · `PROPERTY_ANALYSIS_STRICT` | analyse IA du bâtiment (défaut `claude-sonnet-5`, 40 images) | | |
| 329 | +| `AI_ANALYSIS_DAILY_MAX` · `AI_DAILY_BUDGET_USD` · `AI_MONTHLY_BUDGET_USD` · `LISTING_IMAGE_RETENTION_DAYS` | quotas et budget de l'analyse IA, rétention du cache d'images (30 j) | | |
| 314 | 330 | |
| 315 | 331 | ## Déploiement |
| 316 | 332 | |
@@ -325,13 +341,20 @@ Noms seulement — **aucun secret n'est versionné** (`.env.local` sur le nœud) | ||
| 325 | 341 | | `vrai-prix` | `next start -H 0.0.0.0 -p 8090` | l'app Next.js — pages SSR + API | |
| 326 | 342 | | `vrai-prix-ngrok` | `ngrok http --url=www.vrai-prix.com 8090` | tunnel vers www.vrai-prix.com | |
| 327 | 343 | | `vrai-prix-ingest` | `node scripts/ingest-jdm.mjs` | connecteur incrémental « nouvelles ventes » — lancé à la demande, arrêté au repos | |
| 344 | +| `vrai-prix-immoka-sync` | `npm run immoka:sync` (cron `30 3 * * *`) | snapshot `.backup` d'Immo-Ka sur M4M64b (SSH LAN, clé gardien), rsync delta, ré-évaluation de toutes les annonces vivantes (shards = cœurs − 4), table `vp_eval` + `data/marche-stats.json`, index/FTS, bascule atomique, `pm2 restart vrai-prix` | | |
| 345 | +| `vrai-prix-cost-sync` | `npm run cost:sync` (cron `15 5 * * *`) | connecteurs de la base de coûts (APCHQ, CCQ, StatCan, Canac, BMR, Patrick Morin) → `data/cost.db` | | |
| 328 | 346 | |
| 329 | 347 | ```bash |
| 330 | 348 | # sur M3U96a, après un changement : |
| 331 | 349 | cd ~/apps/vrai-prix && npm run build && pm2 restart vrai-prix |
| 332 | 350 | pm2 logs vrai-prix --lines 30 |
| 351 | +# rafraîchir les annonces à la main (≈ 2 min) / relancer un connecteur de coûts : | |
| 352 | +scripts/immoka-sync.sh # journal : tmp/immoka-sync.log | |
| 353 | +npm run cost:sync -- statcan --force | |
| 333 | 354 | ``` |
| 334 | 355 | |
| 356 | +Le manifeste `mld` (`M1M32:~/dispatch/apps/vrai-prix.json`) exclut `data/`, `tmp/`, `.env.local` de la synchronisation et épingle l'app sur M3U96a (les bases de 2 Go ne voyagent pas). | |
| 357 | + | |
| 335 | 358 | ## Documentation |
| 336 | 359 | |
| 337 | 360 | - **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. |
@@ -351,6 +374,7 @@ pm2 logs vrai-prix --lines 30 | ||
| 351 | 374 | | 2026-08-23/24 | stats v3 (rapports PDF personnalisés), favoris « Mon univers Ka », page `/doc` + PDF, README v3 | |
| 352 | 375 | | 2026-08-25 | refonte front-end v2 « terminal éditorial », KA Tabbar v1, widget ka-agent v4, galerie WebP mobile+desktop | |
| 353 | 376 | | 2026-08-28 | README v4 — visite guidée « le site en 10 pages » (captures live de production, `docs/screenshots/`) | |
| 377 | +| 2026-09-08 | **Méthode du coût** (`/cout`, base de coûts + connecteurs + PDF + 9 outils Ka) et **propriétés à vendre** (`/a-vendre`, copie Immo-Ka ré-évaluée chaque nuit, atelier d'évaluation, analyse IA du bâtiment), `/stats/marche` ; portés du fork UQO Éval et rebrandés | | |
| 354 | 378 | |
| 355 | 379 | ## Écosystème Groupe KA |
| 356 | 380 | |
| 357 | 381 | |