1# ka-stats — module Stats commun Groupe KA (spec v1)23Contrat partagé par les 12 plateformes pour leurs pages **/stats** (tableau de4bord analytique) et l'**export PDF** estampillé Groupe-KA. Le visuel suit le5design system ka-ui (tokens.css) avec l'accent de la marque.67## 1. Page /stats — structure obligatoire (dans cet ordre)891. **Bandeau KPI** : 4–6 grandes cartes (`KpiCard`) — valeur, libellé,10 variation vs période précédente (▲/▼ + %, vert `--green` / rouge `--danger`).112. **Sélecteur de période global** (`PeriodSelector`) : `aujourd'hui · 7 j ·12 30 j · 3 m · 6 m · 12 m · année en cours · tout` + plage personnalisée13 (2 champs date). Toute la page se recalcule (state → refetch dashboard).143. **Graphiques** : courbes d'évolution (`LineChart`, survol = infobulle,15 légende cliquable pour masquer une série, comparaison N vs N-1 en16 pointillé), barres (`BarChart`), anneaux (`Donut`), calendrier de chaleur17 (`CalendarHeatmap`) quand pertinent.184. **Répartition géographique** (par ville/région) quand pertinent — barres19 horizontales triées (pas besoin de vraie carte).205. **Tableaux détaillés** (`DataTable`) : tri par colonne, recherche interne,21 pagination (25/pg), débordement horizontal propre sur mobile (.tbl-wrap).226. **Records & faits marquants** : générés depuis les données (jour record,23 plus forte croissance, meilleure entrée…) — cartes compactes.247. **Fraîcheur** : « Mis à jour le {date heure} » + bouton Rafraîchir.258. **Bouton PDF** bien visible en haut : « Télécharger le rapport PDF » avec26 deux choix (Rapport complet / Synthèse 2 pages). Indicateur de progression27 si > 2 s.2829Responsive : KPI empilés < 768 px, graphiques pleine largeur redimensionnés30(SVG viewBox), tableaux en défilement horizontal contenu, tactile ≥ 44 px.31AUCUNE donnée inventée : une stat indisponible = bloc « Pas encore mesuré »32(carte grise propre), jamais un faux chiffre.3334## 2. API — contrat commun3536`GET /api/stats/dashboard?period=7j|30j|3m|6m|12m|annee|tout|auj&from=YYYY-MM-DD&to=YYYY-MM-DD`3738```jsonc39{40 "updated": "2026-08-17T21:04:00-04:00",41 "period": { "from": "2026-07-18", "to": "2026-08-17", "label": "30 jours" },42 "kpis": [ { "id": "total", "label": "Annonces actives", "value": 33744,43 "unit": "", "delta_pct": 4.2, "direction": "up" } ],44 "series": [ { "id": "vol", "title": "Annonces actives par jour", "unit": "annonces",45 "kind": "line", "points": [{ "t": "2026-07-18", "v": 31200 }],46 "compare": [{ "t": "2025-07-18", "v": 24100 }] } ],47 "breakdowns": [ { "id": "types", "title": "Par type", "kind": "donut",48 "items": [{ "label": "4½", "value": 9120 }] } ],49 "geo": { "title": "Par région", "items": [{ "label": "Montréal", "value": 15680 }] },50 "heatmap": { "title": "Activité", "cells": [{ "date": "2026-08-01", "value": 210 }] },51 "tables": [ { "id": "top", "title": "Top villes", "columns": ["Ville", "Annonces", "Δ 30 j"],52 "rows": [["Montréal", 15680, "+3,1 %"]] } ],53 "records": [ { "label": "Jour record d'ajouts", "value": "412 annonces", "date": "2026-08-09" } ]54}55```5657Champs absents = section masquée. Cache serveur recommandé (≥ 5 min par58période). Les valeurs proviennent des données réelles (DB de la plateforme,59journaux de sync des connecteurs, /api/v1/runs d'API-KA…).6061`GET /api/stats/report?period=…&from=&to=&mode=complet|synthese`62→ `application/pdf`, en-tête `Content-Disposition: attachment; filename=63groupe-ka_<plateforme>_stats_<periode>_<YYYY-MM-DD>.pdf`.6465## 3. PDF — gabarit Groupe-KA (implémentations : `kapdf.py` fpdf2 pour les66apps Python ; les apps Next portent le même gabarit en pdfkit)6768- **Couverture** : cadre encre, kicker « GROUPE KA · RAPPORT STATISTIQUE »,69 wordmark de la plateforme (boîte encre + accent), sous-titre, période70 couverte, date/heure de génération, bande encre au pied avec71 « par Groupe KA — groupe-ka.com ».72- **Sommaire** avec numéros de pages (mode complet).73- **KPI** : grille de cartes (bordure encre, valeur en gros, delta coloré).74- **Graphiques VECTORIELS** (dessinés en primitives, jamais de capture) :75 courbes, barres, anneaux — accent de la plateforme, axes/graduations encre.76- **Tableaux** paginés proprement (lignes zébrées `--surface-2`, jamais77 coupés en deux à cheval sur une ligne).78- **Records** puis **page de fin** : coordonnées Groupe KA (3 courriels +79 rôles d'ecosystem.json, groupe-ka.com), avertissement d'agrégateur,80 mentions légales courtes.81- **Chaque page** : en-tête discret (« Groupe KA · {Plateforme} », filet82 encre) + pied (« © Groupe-KA — {année} — groupe-ka.com · {période} · p. X/Y »).83- A4 portrait, marges 18 mm, typo : Helvetica (fallback sûr) ou fonts TTF du84 DS si présentes. Mode « synthese » = couverture + 1 page KPI/records.8586## 4. Spécifique par plateforme (sections métier attendues)8788- **groupe-ka** : tableau de bord maître — consolidation des 12 (volume total,89 croissance), classement des plateformes, bloc résumé par plateforme + lien90 vers sa page /stats ; « Rapport écosystème complet » = PDF consolidé.91- **lou-ka** : annonces actives/nouvelles/retirées, loyers moyens/médians par92 ville & taille, évolution, répartition par type, top villes.93- **immo-ka** : annonces actives/nouvelles/vendues-retirées, prix moyen/médian94 par ville/région/type, délai de présence, top villes, tension du marché.95- **vrai-prix** : couverture du rôle (unités, valeur totale), estimations96 servies si journalisées, répartitions par municipalité/type, indices marché.97- **auto-ka** : volume par marque/modèle/année/carburant/boîte, prix moyens et98 km moyens par segment, top marques/modèles.99- **fabri-ka** : produits par catégorie/région/boutique, fourchettes de prix,100 nouveautés par période, top catégories.101- **food-ka** : produits suivis, relevés de prix, soldes détectés (baisses/102 hausses, amplitude), top produits en solde, prix moyens par catégorie.103- **resto-ka** : restos par cuisine/ville/gamme, menus & plats, nouveautés/104 fermetures détectées, top établissements.105- **sorti-ka** : événements à venir/passés par catégorie/ville, gratuits vs106 payants, heatmap calendrier, top lieux.107- **crea-ka** : créateurs par plateforme/niche/tier, comptes reliés, top108 créateurs, croissance du répertoire.109- **trouve-ka** : pages indexées, domaines, rythme de crawl (indexées/h),110 erreurs, file frontier, tendances si les requêtes sont journalisées.111- **api-ka** : appels par endpoint/jour/heure, latences moyennes + p95, taux112 d'erreur, top endpoints, uptime (données des middlewares de logging + runs).113- **Transverse (tous)** : volume total agrégé + croissance, connecteurs actifs114 et éléments ajoutés/mis à jour par période (journaux de sync), complétude/115 fraîcheur moyenne des fiches quand mesurable. Trafic web : seulement si des116 journaux d'accès existent — sinon état vide propre.117118## 5. Ajouter une métrique / un graphique / une plateforme1191201 métrique = 1 entrée `kpis[]` ou `series[]` côté API (requête SQL agrégée +121cache) — le front la rend automatiquement. 1 plateforme = implémenter les 2122endpoints du contrat + une page /stats montée sur les composants du kit +123`kapdf.py` (ou gabarit pdfkit) branché sur le même JSON de dashboard.124