# Vrai-Prix — Pipeline de données (documentation de continuité)

Rédigé le 2026-08-18. Important : contrairement aux autres apps Ka, Vrai-Prix n'a AUCUN connecteur runtime. Toute la donnée est produite par un pipeline batch qui tourne sur le laptop (~/Desktop/qc_house_eval/ et ~/Desktop/house/), puis livrée au nœud M3U96a sous forme d'un unique fichier SQLite (data/vraiprix.db, ~1,5 Go). Ce document existe pour que n'importe quelle session future puisse comprendre, auditer et rejouer le pipeline même sans accès à l'historique de conversation.

# Vue d'ensemble

[MAMH — rôles d'évaluation 2021-2026]        [api.qub.ca — transactions]
  Données Québec (FGDB/GPKG, licence            scraping quadtree, token
  ouverte, téléchargement MANUEL)               Bearer recapturé via Safari
        │                                             │
        │  extract_roles.py                           │  ~/Desktop/house/scrape_province.py
        ▼                                             ▼
   unités normalisées  ◄──── merge_transactions.py ──── transactions brutes
                              (fusion spatiale kNN, 2 passes, 99,88 %)
        │
        ▼
   hedonic.py — LightGBM, 4 modèles hédoniques (estimation de valeur)
        │
        ▼
   build_vrai_prix_db.py — assemble data/vraiprix.db (units, transactions,
        │                   market_index, FTS5 units_fts, leads)
        ▼
   build_stats.py — agrégats / index de marché
        │
        ▼
   scp vraiprix.db (~1,5 Go) → M3U96a:~/apps/vrai-prix/data/  → app Next.js

# 1. Sources amont

# 1.1 Rôles d'évaluation foncière (MAMH)

• Quoi : rôles d'évaluation municipale du Québec, millésime 2021-2026 (MAMH — ministère des Affaires municipales et de l'Habitation).
• Où : Données Québec — jeu « Rôles d'évaluation foncière ». Licence ouverte (réutilisation permise avec attribution — Données Québec / MAMH).
• Format : FGDB (Esri File Geodatabase) et/ou GPKG (GeoPackage), téléchargés manuellement (pas d'API d'ingestion automatique — les fichiers sont volumineux et versionnés par millésime).
• Contenu utile : chaque unité d'évaluation (adresse, matricule, usage, géométrie/GPS, valeurs au rôle terrain/bâtiment, caractéristiques physiques — frontage, superficie, année de construction, nb logements…).
• Stockage laptop : sous ~/Desktop/qc_house_eval/ (données brutes + scripts dans scripts/).

# 1.2 Transactions immobilières (api.qub.ca)

• Quoi : transactions de vente résidentielles (prix réel, date d'acte), utilisées pour entraîner les modèles hédoniques et calculer l'indice de marché.
• Comment : scraping par quadtree de l'API api.qub.ca avec ~/Desktop/house/scrape_province.py (sur le laptop) : découpage récursif du territoire en tuiles jusqu'à passer sous le plafond de résultats par requête, couverture provinciale complète.
• Auth : jeton Bearer requis, recapturé manuellement via Safari (ouvrir le site qub.ca, inspecteur web → copier l'en-tête Authorization d'une requête à api.qub.ca, le coller dans le script). Le jeton expire : c'est l'étape manuelle fragile du pipeline (voir « Risques »).

# 2. Étapes du pipeline (laptop — ~/Desktop/qc_house_eval/scripts/)

Ordre d'exécution (chaque étape lit la sortie de la précédente) :

# 3. Livraison au nœud

Le nœud ne fait que servir la base — l'app Next.js (M3U96a, ce repo) lit data/vraiprix.db en lecture seule.

# depuis le laptop, après un build complet :
scp ~/Desktop/qc_house_eval/…/vraiprix.db M3U96a:apps/vrai-prix/data/vraiprix.db
ssh M3U96a 'pm2 restart vrai-prix'   # recharger l'app après remplacement de la BD

• Taille du livrable : ~1,5 Go (dernier fichier livré : 2026-08-08).
• La BD est en WAL (-shm/-wal présents sur le nœud) ; remplacer le .db quand l'app est arrêtée ou juste avant un pm2 restart pour éviter tout mélange de journaux.

# 4. Volumétrie (build livré, vérifiée live sur le nœud 2026-08-18)

• Dernier build : 2026-08-08 (mtime du fichier sur le nœud : 8 août 18:22).

# 5. Complétude des champs (build 2026-08-08)

Les champs manquants sont des trous du rôle MAMH lui-même (certaines municipalités ne publient pas toutes les caractéristiques) — les modèles hédoniques les traitent comme valeurs manquantes natives LightGBM.

# 6. Risques & limites (à connaître avant tout rafraîchissement)

1. Token qub.ca manuel : le Bearer d'api.qub.ca doit être recapturé à la main via Safari à chaque campagne de scraping ; s'il expire en cours de quadtree, relancer scrape_province.py (il est repriseable par tuiles). Aucun renouvellement automatique — point de fragilité n° 1.
2. Pipeline NON reproductible sur le nœud : les données brutes (FGDB/GPKG MAMH, dumps qub.ca), les scripts et les environnements Python (GDAL/ pyogrio pour lire les FGDB, LightGBM) ne vivent que sur le laptop (~/Desktop/qc_house_eval/, ~/Desktop/house/). Si le laptop est perdu, le pipeline doit être reconstruit ; seul le livrable vraiprix.db est sur le nœud (et le repo git ne contient PAS la BD ni les données brutes). → Recommandation : archiver qc_house_eval/scripts/ + house/ (au moins les scripts) sur le NAS ou dans un repo gitsrv dédié.
3. Rôle 2027 à venir : le millésime MAMH suivant (rôles 2024-2029 / publication « 2027 ») exigera de rejouer tout le pipeline : re-télécharger les FGDB/GPKG, revalider les schémas (les noms de couches/champs bougent entre millésimes), ré-entraîner les 4 modèles.
4. Décalage de fraîcheur : la BD servie date du dernier build (2026-08-08) ; l'app n'a aucun mécanisme de mise à jour incrémentale — c'est voulu (batch + livraison atomique d'un seul fichier).

# 7. Procédure de rafraîchissement pas à pas

Sur le laptop :

1. Transactions — recapturer le token : Safari → qub.ca (section immobilier) → inspecteur web → requête vers api.qub.ca → copier le header Authorization: Bearer … → le mettre dans ~/Desktop/house/scrape_province.py → lancer le scraping quadtree (long ; repriseable). Vérifier le volume obtenu vs ~745 k.
2. Rôles — si nouveau millésime MAMH : télécharger manuellement les FGDB/GPKG depuis Données Québec dans ~/Desktop/qc_house_eval/.
3. cd ~/Desktop/qc_house_eval/scripts/ puis, dans l'ordre : python3 extract_roles.py → python3 merge_transactions.py (contrôler le taux d'appariement, attendu ≥ 99,8 %) → python3 hedonic.py (4 modèles ; contrôler les métriques de validation avant de continuer) → python3 build_vrai_prix_db.py → python3 build_stats.py.
4. Contrôles qualité sur le vraiprix.db produit : SELECT COUNT(*) FROM units; (~3,7 M), SELECT COUNT(*) FROM transactions; (~745 k+), SELECT COUNT(*) FROM market_index;, complétude GPS = 100 %, spot-check de quelques adresses connues dans units_fts.
5. Livraison : scp du fichier vers M3U96a:apps/vrai-prix/data/vraiprix.db puis ssh M3U96a 'pm2 restart vrai-prix'.
6. Vérification en prod : ouvrir le site (vrai-prix), chercher une adresse, vérifier /stats, puis noter la date de build ici (section 4) et committer la mise à jour de ce document sur le nœud (remote-first : git add docs/PIPELINE-DONNEES.md && git commit && git push origin main).

# 8. Attribution

Les données du rôle d'évaluation proviennent du MAMH via Données Québec (licence ouverte — attribution requise). Les transactions servent au calcul de modèles et d'indices agrégés ; les pages publiques n'exposent pas la source brute qub.ca.