Python 33.5%
JavaScript 30.1%
TypeScript 25%
CSS 10%
Shell 1.4%
1# ka-stats — module Stats commun Groupe KA (spec v3)23Contrat partagé par les plateformes pour leurs pages **/stats** (tableau de4bord analytique) et les **exports PDF** estampillés Groupe-KA. Le visuel suit5le design system ka-ui (tokens.css) avec l'accent de la marque.67**v2 (2026-08-19)** : sparklines dans les KPI, jauges, multi-courbes,8barres empilées, distributions (histogrammes), heatmap horaire 7×24, deltas9sur les répartitions, statistiques de séries (min/max/moy/méd/σ), et **510rapports PDF** au lieu de 2. Tous les nouveaux champs sont **optionnels** :11un dashboard v1 reste valide et se rend tel quel.1213**v3 (2026-08-23)** : **rapports personnalisés** — l'utilisateur compose son14propre rapport PDF bloc par bloc : choix des données (catalogue dérivé du15dashboard), du **rendu par bloc** (courbe/aire/barres/anneau/histogramme/16heatmap/tableau…), de l'ordre, avec **modèles sauvegardés** (localStorage du17site). Deux endpoints (`/api/stats/catalog`, `POST /api/stats/report/custom`,18voir §3bis) + un constructeur dans la page /stats (`ReportBuilder` du kit —19bouton « 🛠 Rapport personnalisé » à côté du menu PDF). Le PDF garde le20gabarit estampillé Groupe-KA avec l'accent de la plateforme. v2 inchangée.2122## 1. Page /stats — structure obligatoire (dans cet ordre)23241. **Bandeau KPI** : 6–10 grandes cartes (`KpiCard`) — valeur, libellé,25 variation vs période précédente (▲/▼ + %, vert `--green` / rouge26 `--danger`), **sparkline** de tendance quand une série existe.272. **Sélecteur de période global** (`PeriodSelector`) : `aujourd'hui · 7 j ·28 30 j · 3 m · 6 m · 12 m · année en cours · tout` + plage personnalisée29 (2 champs date). Toute la page se recalcule (state → refetch dashboard).303. **Jauges** (`GaugeCard`) quand pertinent : taux, couvertures, complétude.314. **Graphiques d'évolution** : courbes/aires (`LineChart`, survol =32 infobulle, légende cliquable, comparaison N vs N-1 en pointillé), barres33 verticales (`VBarChart` — volumes quotidiens), **multi-courbes ≤ 4 séries**34 (`MultiLineChart` — motifs de trait distincts, jamais la couleur seule),35 **barres empilées** (`StackedBarChart` — composition dans le temps).36 Sous les courbes clés : `StatSummary` (min/max/moyenne/médiane/écart-type).375. **Répartitions** : barres horizontales (`BarChart`, deltas optionnels),38 anneaux (`Donut`), **distributions/histogrammes** (`Histogram`).396. **Répartition géographique** (par ville/région) — barres horizontales40 triées (pas besoin de vraie carte).417. **Calendriers** : `CalendarHeatmap` (26 semaines) et, quand l'activité42 horaire est journalisée, `HourHeatmap` (7 jours × 24 h).438. **Tableaux détaillés** (`DataTable`) : tri par colonne, recherche interne,44 pagination (25/pg), débordement horizontal propre sur mobile (.tbl-wrap).45 Viser 3 à 5 tableaux par plateforme.469. **Records & faits marquants** : générés depuis les données (jour record,47 plus forte croissance, meilleure entrée…) — cartes compactes, 6–12.4810. **Fraîcheur** : « Mis à jour le {date heure} » + bouton Rafraîchir.4911. **Bouton PDF** bien visible en haut (`PdfButton`) : bouton principal50 « Rapport PDF complet » + menu « Autres rapports ▾ » listant les51 **5 rapports** (voir §3). Indicateur de progression si > 2 s.5253Responsive : KPI empilés < 768 px, graphiques pleine largeur redimensionnés54(SVG viewBox), tableaux en défilement horizontal contenu, tactile ≥ 44 px.55AUCUNE donnée inventée : une stat indisponible = bloc « Pas encore mesuré »56(carte grise propre), jamais un faux chiffre.5758Accessibilité (règles fermes) : un seul axe Y par graphique (jamais de59double échelle) ; ≥ 2 séries ⇒ légende obligatoire ; l'identité d'une série60multi-courbes passe par le **motif de trait** en plus de la couleur ; le61texte reste en encre (jamais coloré à la couleur de série) ; chaque62graphique a son infobulle de survol et un équivalent tableau existe.6364## 2. API — contrat commun6566`GET /api/stats/dashboard?period=7j|30j|3m|6m|12m|annee|tout|auj&from=YYYY-MM-DD&to=YYYY-MM-DD`6768```jsonc69{70 "updated": "2026-08-19T01:00:00-04:00",71 "period": { "from": "2026-07-20", "to": "2026-08-19", "label": "30 jours" },72 "kpis": [ { "id": "total", "label": "Annonces actives", "value": 33744,73 "unit": "", "delta_pct": 4.2, "direction": "up",74 "spark": [{ "t": "2026-08-01", "v": 31200 }] } ], // spark optionnel75 "gauges": [ { "id": "geo", "label": "Fiches géolocalisées", "value": 92,76 "max": 100, "unit": "%" } ], // optionnel77 "series": [ { "id": "vol", "title": "Annonces actives par jour", "unit": "annonces",78 "kind": "line", // line | bar | area79 "points": [{ "t": "2026-07-20", "v": 31200 }],80 "compare": [{ "t": "2025-07-20", "v": 24100 }] } ],81 "multiseries": [ { "id": "seg", "title": "Prix médian par taille", "unit": "$",82 "series": [ { "label": "3½", "points": [/* … */] },83 { "label": "4½", "points": [/* … */] } ] } ], // ≤ 484 "stacked": [ { "id": "src", "title": "Ajouts par source", "unit": "ajouts",85 "keys": ["Kijiji", "Centris", "Autres"],86 "points": [{ "t": "2026-08-01", "values": [120, 80, 30] }] } ],87 "breakdowns": [ { "id": "types", "title": "Par type", "kind": "donut", // donut | bars88 "items": [{ "label": "4½", "value": 9120, "delta_pct": 2.1 }] } ],89 "distributions": [ { "id": "prix", "title": "Distribution des loyers", "unit": "annonces",90 "bins": [{ "label": "800-1000$", "value": 3120 }] } ],91 "geo": { "title": "Par région", "items": [{ "label": "Montréal", "value": 15680 }] },92 "heatmap": { "title": "Activité", "cells": [{ "date": "2026-08-01", "value": 210 }] },93 "hourly": { "title": "Activité par heure",94 "cells": [{ "dow": 0, "hour": 9, "value": 40 }] }, // dow 0=lun … 6=dim95 "tables": [ { "id": "top", "title": "Top villes", "columns": ["Ville", "Annonces", "Δ 30 j"],96 "rows": [["Montréal", 15680, "+3,1 %"]] } ],97 "records": [ { "label": "Jour record d'ajouts", "value": "412 annonces", "date": "2026-08-09" } ]98}99```100101Champs absents = section masquée. Cache serveur recommandé (≥ 5 min par102période). Les valeurs proviennent des données réelles (DB de la plateforme,103journaux de sync des connecteurs, /api/v1/runs d'API-KA…). Arrondir les104`delta_pct` à 1 décimale côté serveur.105106## 3. Rapports PDF — 5 modes107108`GET /api/stats/report?period=…&from=&to=&mode=complet|synthese|tendances|repartitions|donnees`109→ `application/pdf`, en-tête `Content-Disposition: attachment; filename=110groupe-ka_<plateforme>_stats_<periode>[_<mode>]_<YYYY-MM-DD>.pdf`111(pas de suffixe pour `complet` — rétrocompatible v1 ; `kapdf.filename()`112accepte maintenant `mode` en 3e argument).113114| Mode | Contenu |115|---|---|116| `complet` | tout : sommaire, KPI, jauges, séries + stats de séries, multi-séries, empilées, répartitions, distributions, géo, heatmap horaire, tableaux (200 lignes), records |117| `synthese` | couverture + KPI + jauges + records (2–3 pages) |118| `tendances` | KPI + toutes les séries temporelles + min/max/moy/méd/σ + records |119| `repartitions` | breakdowns, distributions, géo, activité horaire |120| `donnees` | tous les tableaux en version longue (400 lignes) |121122Un `mode` inconnu retombe sur `complet`. Le gabarit (implémentations :123`kapdf.py` fpdf2 pour les apps Python ; les apps Next portent le même124gabarit en pdfkit) :125126- **Couverture** : cadre encre, kicker « GROUPE KA · RAPPORT STATISTIQUE »,127 wordmark de la plateforme (boîte encre + accent), **type de rapport**,128 période couverte, date/heure de génération, bande encre au pied avec129 « par Groupe KA — groupe-ka.com ».130- **Sommaire** avec numéros de pages (modes complet et donnees).131- **KPI** : grille de cartes (bordure encre, valeur en gros, delta coloré132 arrondi à 1 décimale). **Jauges** : demi-arcs accent.133- **Graphiques VECTORIELS** (dessinés en primitives, jamais de capture) :134 courbes/aires, barres verticales, multi-courbes (motifs distincts),135 empilées (nuances d'accent), anneaux, heatmap horaire — accent de la136 plateforme, axes/graduations encre.137- **Tableaux** paginés proprement (lignes zébrées `--surface-2`, jamais138 coupés en deux à cheval sur une ligne).139- **Records** puis **page de fin** : coordonnées Groupe KA (3 courriels +140 rôles d'ecosystem.json, groupe-ka.com), avertissement d'agrégateur,141 mentions légales courtes.142- **Chaque page** : en-tête discret (« Groupe KA · {Plateforme} », filet143 encre) + pied (« © Groupe-KA — {année} — groupe-ka.com · {période} · p. X/Y »).144- A4 portrait, marges 18 mm, typo : Helvetica (fallback sûr) ou fonts TTF du145 DS si présentes.146147## 3bis. Rapports personnalisés (v3)148149### Catalogue150151`GET /api/stats/catalog?period=…&from=&to=` →152153```jsonc154{ "updated": "…", "period": { … },155 "blocks": [ { "key": "series:ajouts", // section[:id] — clé stable156 "section": "series",157 "title": "Événements ajoutés par jour",158 "renders": ["line","area","bar","table"], // rendus compatibles159 "default_render": "line",160 "count": 30 } ] } // taille indicative (optionnel)161```162163Sections → rendus : `kpis` cards|table · `gauges` gauges|table ·164`series:<id>` line|area|bar|table · `multiseries:<id>` lines|table ·165`stacked:<id>` stacked|table · `breakdowns:<id>` donut|bars|table ·166`distributions:<id>` histogram|table · `geo` bars|table ·167`heatmap` heatmap|table · `hourly` heatmap|table · `tables:<id>` table ·168`records` cards|table. **Toute donnée a un équivalent tableau.** Le catalogue169est dérivé du dashboard (implémentation : `kapdf.catalog(dash)` /170`catalogFromDashboard()` en TS) — zéro maintenance quand une métrique s'ajoute.171172### Génération173174`POST /api/stats/report/custom` — corps JSON :175176```jsonc177{ "title": "Revue mensuelle", // ≤ 80 car., affiché en couverture178 "period": "30j", "from": "", "to": "", // mêmes règles que le dashboard179 "blocks": [ { "key": "kpis", "render": "cards" },180 { "key": "series:ajouts", "render": "bar" } ] } // ordre = ordre du PDF181```182183→ `application/pdf`, filename `groupe-ka_<plateforme>_stats_<periode>_personnalise_<date>.pdf`.184Clés inconnues ignorées ; rendu incompatible → rendu par défaut ; aucun bloc185valide → **400**. Maximum 40 blocs. Couverture : type = « Rapport186personnalisé — {title} » ; sommaire ; page de fin habituelle. Un même bloc187peut apparaître plusieurs fois (ex. graphique + tableau).188189### Constructeur (front, kit)190191`ReportBuilder` (kacharts.tsx ; port vanilla pour les SPA sans React) :192panneau modal 2 colonnes — catalogue groupé par section à gauche, composition193ordonnée à droite (↑ ↓ ✕, sélecteur de rendu par bloc, titre). **Modèles** :194sauvegarde/chargement/suppression nommés en localStorage (clé195`ka-stats-rapports`, propre à l'origine du site). Bouton « Générer le PDF »196→ POST + téléchargement blob. États busy/erreur propres, tactile ≥ 44 px,197z-index `var(--z-modal, 900)`.198199## 4. Spécifique par plateforme (sections métier attendues)200201- **groupe-ka** : tableau de bord maître — consolidation des plateformes202 (volume total, croissance), classement, bloc résumé par plateforme + lien203 vers sa page /stats ; « Rapport écosystème complet » = PDF consolidé.204- **lou-ka** : annonces actives/nouvelles/retirées, loyers moyens/médians par205 ville & taille (multiseries), distribution des loyers, évolution,206 répartition par type, top villes, sources (stacked).207- **immo-ka** : annonces actives/nouvelles/vendues-retirées, prix208 moyen/médian par ville/région/type (multiseries), distribution des prix,209 délai de présence, top villes, tension du marché.210- **vrai-prix** : couverture du rôle (unités, valeur totale), estimations211 servies si journalisées, répartitions par municipalité/type, distribution212 des valeurs, indices marché.213- **auto-ka** : volume par marque/modèle/année/carburant/boîte, prix moyens214 et km moyens par segment (multiseries), distributions prix/km/année,215 top marques/modèles.216- **fabri-ka** : produits par catégorie/région/boutique, fourchettes de prix217 (distribution), nouveautés par période, top catégories.218- **food-ka** : produits suivis, relevés de prix, soldes détectés219 (baisses/hausses, amplitude — stacked), top produits en solde, prix moyens220 par catégorie, distribution des rabais.221- **resto-ka** : restos par cuisine/ville/gamme, menus & plats, distribution222 des prix de plats, nouveautés/fermetures détectées, top établissements.223- **sorti-ka** : événements à venir/passés par catégorie/ville, gratuits vs224 payants (stacked), heatmap calendrier + horaire, top lieux.225- **crea-ka** : créateurs par plateforme/niche/tier, comptes reliés226 (stacked par plateforme), distribution des audiences, top créateurs,227 croissance du répertoire.228- **trouve-ka** : pages indexées, domaines, rythme de crawl (indexées/h —229 hourly), erreurs, file frontier, tendances des requêtes journalisées.230- **api-ka** : appels par endpoint/jour/heure (hourly), latences moyennes +231 p95 (multiseries), taux d'erreur, top endpoints/clés, uptime.232- **job-ka** : offres actives/nouvelles/expirées par catégorie/ville/233 entreprise, distribution des salaires affichés, top employeurs.234- **Transverse (tous)** : volume total agrégé + croissance, connecteurs235 actifs et éléments ajoutés/mis à jour par période (journaux de sync —236 stacked par source quand possible), complétude/fraîcheur moyenne des237 fiches quand mesurable (jauges). Trafic web : seulement si des journaux238 d'accès existent — sinon état vide propre.239240## 5. Ajouter une métrique / un graphique / une plateforme2412421 métrique = 1 entrée `kpis[]`, `series[]`, `multiseries[]`, `stacked[]`,243`distributions[]` ou `gauges[]` côté API (requête SQL agrégée + cache) — le244front la rend automatiquement. 1 plateforme = implémenter les 2 endpoints du245contrat + une page /stats montée sur les composants du kit + `kapdf.py` (ou246gabarit pdfkit) branché sur le même JSON de dashboard.247