docs: PIPELINE-DONNEES.md — pipeline batch de bout en bout (continuité) · 4eef4f1 · vrai-prix

docs: PIPELINE-DONNEES.md — pipeline batch de bout en bout (continuité)

Documente le pipeline qui produit data/vraiprix.db (il tourne sur le laptop,
pas sur le nœud) : sources amont (rôles MAMH 2021-2026 FGDB/GPKG Données
Québec licence ouverte ; transactions api.qub.ca scrapées en quadtree avec
token Bearer manuel), étapes (extract_roles → merge_transactions kNN 2 passes
99,88 % → hedonic LightGBM 4 modèles → build_vrai_prix_db → build_stats),
livraison scp 1,5 Go vers M3U96a, volumétrie vérifiée live (3 747 008 unités,
745 119 transactions, market_index 268), complétude (GPS 100 %, frontage
83 %, année 79 %), risques (token manuel, non-reproductible sur nœud, rôle
2027) et procédure de rafraîchissement pas à pas.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Simon-Pierre Boucher committed 1 mo ago (Aug 18, 2026) parent a4133a5

1 changed file +175 −0

added docs/PIPELINE-DONNEES.md +175 −0

		`@@ -0,0 +1,175 @@`
	1	+# Vrai-Prix — Pipeline de données (documentation de continuité)
	2	+
	3	+> Rédigé le 2026-08-18. **Important : contrairement aux autres apps Ka, Vrai-Prix
	4	+> n'a AUCUN connecteur runtime.** Toute la donnée est produite par un pipeline
	5	+> batch qui tourne sur le laptop (`~/Desktop/qc_house_eval/` et
	6	+> `~/Desktop/house/`), puis livrée au nœud M3U96a sous forme d'un unique
	7	+> fichier SQLite (`data/vraiprix.db`, ~1,5 Go). Ce document existe pour que
	8	+> n'importe quelle session future puisse comprendre, auditer et rejouer le
	9	+> pipeline même sans accès à l'historique de conversation.
	10	+
	11	+## Vue d'ensemble
	12	+
	13	+```
	14	+[MAMH — rôles d'évaluation 2021-2026] [api.qub.ca — transactions]
	15	+ Données Québec (FGDB/GPKG, licence scraping quadtree, token
	16	+ ouverte, téléchargement MANUEL) Bearer recapturé via Safari
	17	+ │ │
	18	+ │ extract_roles.py │ ~/Desktop/house/scrape_province.py
	19	+ ▼ ▼
	20	+ unités normalisées ◄──── merge_transactions.py ──── transactions brutes
	21	+ (fusion spatiale kNN, 2 passes, 99,88 %)
	22	+ │
	23	+ ▼
	24	+ hedonic.py — LightGBM, 4 modèles hédoniques (estimation de valeur)
	25	+ │
	26	+ ▼
	27	+ build_vrai_prix_db.py — assemble data/vraiprix.db (units, transactions,
	28	+ │ market_index, FTS5 units_fts, leads)
	29	+ ▼
	30	+ build_stats.py — agrégats / index de marché
	31	+ │
	32	+ ▼
	33	+ scp vraiprix.db (~1,5 Go) → M3U96a:~/apps/vrai-prix/data/ → app Next.js
	34	+```
	35	+
	36	+## 1. Sources amont
	37	+
	38	+### 1.1 Rôles d'évaluation foncière (MAMH)
	39	+
	40	+- Quoi : rôles d'évaluation municipale du Québec, millésime 2021-2026
	41	+ (MAMH — ministère des Affaires municipales et de l'Habitation).
	42	+- Où : [Données Québec](https://www.donneesquebec.ca/) — jeu « Rôles
	43	+ d'évaluation foncière ». Licence ouverte (réutilisation permise avec
	44	+ attribution — Données Québec / MAMH).
	45	+- Format : FGDB (Esri File Geodatabase) et/ou GPKG (GeoPackage),
	46	+ téléchargés manuellement (pas d'API d'ingestion automatique — les
	47	+ fichiers sont volumineux et versionnés par millésime).
	48	+- Contenu utile : chaque unité d'évaluation (adresse, matricule, usage,
	49	+ géométrie/GPS, valeurs au rôle terrain/bâtiment, caractéristiques physiques
	50	+ — frontage, superficie, année de construction, nb logements…).
	51	+- Stockage laptop : sous `~/Desktop/qc_house_eval/` (données brutes +
	52	+ scripts dans `scripts/`).
	53	+
	54	+### 1.2 Transactions immobilières (api.qub.ca)
	55	+
	56	+- Quoi : transactions de vente résidentielles (prix réel, date d'acte),
	57	+ utilisées pour entraîner les modèles hédoniques et calculer l'indice de
	58	+ marché.
	59	+- Comment : scraping par quadtree de l'API `api.qub.ca` avec
	60	+ `~/Desktop/house/scrape_province.py` (sur le laptop) : découpage
	61	+ récursif du territoire en tuiles jusqu'à passer sous le plafond de
	62	+ résultats par requête, couverture provinciale complète.
	63	+- Auth : jeton Bearer requis, recapturé manuellement via Safari
	64	+ (ouvrir le site qub.ca, inspecteur web → copier l'en-tête Authorization
	65	+ d'une requête à `api.qub.ca`, le coller dans le script). Le jeton expire :
	66	+ c'est l'étape manuelle fragile du pipeline (voir « Risques »).
	67	+
	68	+## 2. Étapes du pipeline (laptop — `~/Desktop/qc_house_eval/scripts/`)
	69	+
	70	+Ordre d'exécution (chaque étape lit la sortie de la précédente) :
	71	+
	72	+\| # \| Script \| Rôle \|
	73	+\|---\|---\|---\|
	74	+\| 0 \| `~/Desktop/house/scrape_province.py` \| scraping quadtree des transactions api.qub.ca (token Bearer manuel) — préalable, peut tourner indépendamment \|
	75	+\| 1 \| `extract_roles.py` \| extraction/normalisation des unités d'évaluation depuis les FGDB/GPKG MAMH (usages résidentiels, champs canoniques, GPS) \|
	76	+\| 2 \| `merge_transactions.py` \| fusion spatiale kNN en 2 passes des transactions sur les unités du rôle — taux d'appariement 99,88 % \|
	77	+\| 3 \| `hedonic.py` \| entraînement LightGBM — 4 modèles hédoniques (par grande famille de propriété) → valeur estimée « vrai prix » par unité \|
	78	+\| 4 \| `build_vrai_prix_db.py` \| assemblage du SQLite final `vraiprix.db` : tables `units`, `transactions`, `market_index`, index plein-texte FTS5 (`units_fts*`), table applicative `leads` \|
	79	+\| 5 \| `build_stats.py` \| agrégats statistiques / indice de marché (alimente `market_index` et la page /stats) \|
	80	+
	81	+## 3. Livraison au nœud
	82	+
	83	+Le nœud ne fait que servir la base — l'app Next.js (M3U96a, ce repo) lit
	84	+`data/vraiprix.db` en lecture seule.
	85	+
	86	+```bash
	87	+# depuis le laptop, après un build complet :
	88	+scp ~/Desktop/qc_house_eval/…/vraiprix.db M3U96a:apps/vrai-prix/data/vraiprix.db
	89	+ssh M3U96a 'pm2 restart vrai-prix' # recharger l'app après remplacement de la BD
	90	+```
	91	+
	92	+- Taille du livrable : ~1,5 Go (dernier fichier livré : 2026-08-08).
	93	+- La BD est en WAL (`-shm`/`-wal` présents sur le nœud) ; remplacer le `.db`
	94	+ quand l'app est arrêtée ou juste avant un `pm2 restart` pour éviter tout
	95	+ mélange de journaux.
	96	+
	97	+## 4. Volumétrie (build livré, vérifiée live sur le nœud 2026-08-18)
	98	+
	99	+\| Table \| Lignes \| Note \|
	100	+\|---\|---\|---\|
	101	+\| `units` \| 3 747 008 \| unités d'évaluation résidentielles, province entière \|
	102	+\| `transactions` \| 745 119 \| ventes appariées (kNN 2 passes, 99,88 %) \|
	103	+\| `market_index` \| 268 \| lignes d'indice de marché (build_stats.py) \|
	104	+\| `units_fts` (+`_data`/`_idx`/`_config`/`_docsize`) \| — \| index FTS5 de recherche d'adresses \|
	105	+\| `leads` \| — \| table applicative (demandes des visiteurs), remplie par l'app, PAS par le pipeline \|
	106	+
	107	+- Dernier build : 2026-08-08 (mtime du fichier sur le nœud : 8 août 18:22).
	108	+
	109	+## 5. Complétude des champs (build 2026-08-08)
	110	+
	111	+\| Champ \| Complétude \|
	112	+\|---\|---\|
	113	+\| GPS (lat/lng des unités) \| 100 % \|
	114	+\| Frontage \| 83 % \|
	115	+\| Année de construction \| 79 % \|
	116	+
	117	+Les champs manquants sont des trous du rôle MAMH lui-même (certaines
	118	+municipalités ne publient pas toutes les caractéristiques) — les modèles
	119	+hédoniques les traitent comme valeurs manquantes natives LightGBM.
	120	+
	121	+## 6. Risques & limites (à connaître avant tout rafraîchissement)
	122	+
	123	+1. Token qub.ca manuel : le Bearer d'api.qub.ca doit être recapturé à la
	124	+ main via Safari à chaque campagne de scraping ; s'il expire en cours de
	125	+ quadtree, relancer `scrape_province.py` (il est repriseable par tuiles).
	126	+ Aucun renouvellement automatique — point de fragilité n° 1.
	127	+2. Pipeline NON reproductible sur le nœud : les données brutes (FGDB/GPKG
	128	+ MAMH, dumps qub.ca), les scripts et les environnements Python (GDAL/
	129	+ pyogrio pour lire les FGDB, LightGBM) ne vivent que sur le laptop
	130	+ (`~/Desktop/qc_house_eval/`, `~/Desktop/house/`). Si le laptop est perdu,
	131	+ le pipeline doit être reconstruit ; seul le livrable `vraiprix.db` est sur
	132	+ le nœud (et le repo git ne contient PAS la BD ni les données brutes).
	133	+ → Recommandation : archiver `qc_house_eval/scripts/` + `house/` (au moins
	134	+ les scripts) sur le NAS ou dans un repo gitsrv dédié.
	135	+3. Rôle 2027 à venir : le millésime MAMH suivant (rôles 2024-2029 /
	136	+ publication « 2027 ») exigera de rejouer tout le pipeline : re-télécharger
	137	+ les FGDB/GPKG, revalider les schémas (les noms de couches/champs bougent
	138	+ entre millésimes), ré-entraîner les 4 modèles.
	139	+4. Décalage de fraîcheur : la BD servie date du dernier build (2026-08-08) ;
	140	+ l'app n'a aucun mécanisme de mise à jour incrémentale — c'est voulu
	141	+ (batch + livraison atomique d'un seul fichier).
	142	+
	143	+## 7. Procédure de rafraîchissement pas à pas
	144	+
	145	+Sur le laptop :
	146	+
	147	+1. Transactions — recapturer le token : Safari → qub.ca (section
	148	+ immobilier) → inspecteur web → requête vers `api.qub.ca` → copier le
	149	+ header `Authorization: Bearer …` → le mettre dans
	150	+ `~/Desktop/house/scrape_province.py` → lancer le scraping quadtree
	151	+ (long ; repriseable). Vérifier le volume obtenu vs ~745 k.
	152	+2. Rôles — si nouveau millésime MAMH : télécharger manuellement les
	153	+ FGDB/GPKG depuis Données Québec dans `~/Desktop/qc_house_eval/`.
	154	+3. `cd ~/Desktop/qc_house_eval/scripts/` puis, dans l'ordre :
	155	+ `python3 extract_roles.py` → `python3 merge_transactions.py` (contrôler le
	156	+ taux d'appariement, attendu ≥ 99,8 %) → `python3 hedonic.py` (4 modèles ;
	157	+ contrôler les métriques de validation avant de continuer) →
	158	+ `python3 build_vrai_prix_db.py` → `python3 build_stats.py`.
	159	+4. Contrôles qualité sur le `vraiprix.db` produit :
	160	+ `SELECT COUNT() FROM units;` (~3,7 M), `SELECT COUNT() FROM transactions;`
	161	+ (~745 k+), `SELECT COUNT(*) FROM market_index;`, complétude GPS = 100 %,
	162	+ spot-check de quelques adresses connues dans `units_fts`.
	163	+5. Livraison : `scp` du fichier vers `M3U96a:apps/vrai-prix/data/vraiprix.db`
	164	+ puis `ssh M3U96a 'pm2 restart vrai-prix'`.
	165	+6. Vérification en prod : ouvrir le site (vrai-prix), chercher une adresse,
	166	+ vérifier /stats, puis noter la date de build ici (section 4) et committer
	167	+ la mise à jour de ce document sur le nœud (remote-first :
	168	+ `git add docs/PIPELINE-DONNEES.md && git commit && git push origin main`).
	169	+
	170	+## 8. Attribution
	171	+
	172	+Les données du rôle d'évaluation proviennent du MAMH via Données Québec
	173	+(licence ouverte — attribution requise). Les transactions servent au calcul
	174	+de modèles et d'indices agrégés ; les pages publiques n'exposent pas la
	175	+source brute qub.ca.
	176