# ka-stats — module Stats commun Groupe KA (spec v1)

Contrat partagé par les 12 plateformes pour leurs pages /stats (tableau de bord analytique) et l'export PDF estampillé Groupe-KA. Le visuel suit le design system ka-ui (tokens.css) avec l'accent de la marque.

# 1. Page /stats — structure obligatoire (dans cet ordre)

1. Bandeau KPI : 4–6 grandes cartes (KpiCard) — valeur, libellé, variation vs période précédente (▲/▼ + %, vert --green / rouge --danger).
2. Sélecteur de période global (PeriodSelector) : aujourd'hui · 7 j · 30 j · 3 m · 6 m · 12 m · année en cours · tout + plage personnalisée (2 champs date). Toute la page se recalcule (state → refetch dashboard).
3. Graphiques : courbes d'évolution (LineChart, survol = infobulle, légende cliquable pour masquer une série, comparaison N vs N-1 en pointillé), barres (BarChart), anneaux (Donut), calendrier de chaleur (CalendarHeatmap) quand pertinent.
4. Répartition géographique (par ville/région) quand pertinent — barres horizontales triées (pas besoin de vraie carte).
5. Tableaux détaillés (DataTable) : tri par colonne, recherche interne, pagination (25/pg), débordement horizontal propre sur mobile (.tbl-wrap).
6. Records & faits marquants : générés depuis les données (jour record, plus forte croissance, meilleure entrée…) — cartes compactes.
7. Fraîcheur : « Mis à jour le {date heure} » + bouton Rafraîchir.
8. Bouton PDF bien visible en haut : « Télécharger le rapport PDF » avec deux choix (Rapport complet / Synthèse 2 pages). Indicateur de progression si > 2 s.

Responsive : KPI empilés < 768 px, graphiques pleine largeur redimensionnés (SVG viewBox), tableaux en défilement horizontal contenu, tactile ≥ 44 px. AUCUNE donnée inventée : une stat indisponible = bloc « Pas encore mesuré » (carte grise propre), jamais un faux chiffre.

# 2. API — contrat commun

GET /api/stats/dashboard?period=7j|30j|3m|6m|12m|annee|tout|auj&from=YYYY-MM-DD&to=YYYY-MM-DD

{
  "updated": "2026-08-17T21:04:00-04:00",
  "period": { "from": "2026-07-18", "to": "2026-08-17", "label": "30 jours" },
  "kpis": [ { "id": "total", "label": "Annonces actives", "value": 33744,
              "unit": "", "delta_pct": 4.2, "direction": "up" } ],
  "series": [ { "id": "vol", "title": "Annonces actives par jour", "unit": "annonces",
                "kind": "line", "points": [{ "t": "2026-07-18", "v": 31200 }],
                "compare": [{ "t": "2025-07-18", "v": 24100 }] } ],
  "breakdowns": [ { "id": "types", "title": "Par type", "kind": "donut",
                    "items": [{ "label": "4½", "value": 9120 }] } ],
  "geo": { "title": "Par région", "items": [{ "label": "Montréal", "value": 15680 }] },
  "heatmap": { "title": "Activité", "cells": [{ "date": "2026-08-01", "value": 210 }] },
  "tables": [ { "id": "top", "title": "Top villes", "columns": ["Ville", "Annonces", "Δ 30 j"],
                "rows": [["Montréal", 15680, "+3,1 %"]] } ],
  "records": [ { "label": "Jour record d'ajouts", "value": "412 annonces", "date": "2026-08-09" } ]
}

Champs absents = section masquée. Cache serveur recommandé (≥ 5 min par période). Les valeurs proviennent des données réelles (DB de la plateforme, journaux de sync des connecteurs, /api/v1/runs d'API-KA…).

GET /api/stats/report?period=…&from=&to=&mode=complet|synthese → application/pdf, en-tête Content-Disposition: attachment; filename= groupe-ka_<plateforme>_stats_<periode>_<YYYY-MM-DD>.pdf.

# 3. PDF — gabarit Groupe-KA (implémentations : kapdf.py fpdf2 pour les

apps Python ; les apps Next portent le même gabarit en pdfkit)

• Couverture : cadre encre, kicker « GROUPE KA · RAPPORT STATISTIQUE », wordmark de la plateforme (boîte encre + accent), sous-titre, période couverte, date/heure de génération, bande encre au pied avec « par Groupe KA — groupe-ka.com ».
• Sommaire avec numéros de pages (mode complet).
• KPI : grille de cartes (bordure encre, valeur en gros, delta coloré).
• Graphiques VECTORIELS (dessinés en primitives, jamais de capture) : courbes, barres, anneaux — accent de la plateforme, axes/graduations encre.
• Tableaux paginés proprement (lignes zébrées --surface-2, jamais coupés en deux à cheval sur une ligne).
• Records puis page de fin : coordonnées Groupe KA (3 courriels + rôles d'ecosystem.json, groupe-ka.com), avertissement d'agrégateur, mentions légales courtes.
• Chaque page : en-tête discret (« Groupe KA · {Plateforme} », filet encre) + pied (« © Groupe-KA — {année} — groupe-ka.com · {période} · p. X/Y »).
• A4 portrait, marges 18 mm, typo : Helvetica (fallback sûr) ou fonts TTF du DS si présentes. Mode « synthese » = couverture + 1 page KPI/records.

# 4. Spécifique par plateforme (sections métier attendues)

• groupe-ka : tableau de bord maître — consolidation des 12 (volume total, croissance), classement des plateformes, bloc résumé par plateforme + lien vers sa page /stats ; « Rapport écosystème complet » = PDF consolidé.
• lou-ka : annonces actives/nouvelles/retirées, loyers moyens/médians par ville & taille, évolution, répartition par type, top villes.
• immo-ka : annonces actives/nouvelles/vendues-retirées, prix moyen/médian par ville/région/type, délai de présence, top villes, tension du marché.
• vrai-prix : couverture du rôle (unités, valeur totale), estimations servies si journalisées, répartitions par municipalité/type, indices marché.
• auto-ka : volume par marque/modèle/année/carburant/boîte, prix moyens et km moyens par segment, top marques/modèles.
• fabri-ka : produits par catégorie/région/boutique, fourchettes de prix, nouveautés par période, top catégories.
• food-ka : produits suivis, relevés de prix, soldes détectés (baisses/ hausses, amplitude), top produits en solde, prix moyens par catégorie.
• resto-ka : restos par cuisine/ville/gamme, menus & plats, nouveautés/ fermetures détectées, top établissements.
• sorti-ka : événements à venir/passés par catégorie/ville, gratuits vs payants, heatmap calendrier, top lieux.
• crea-ka : créateurs par plateforme/niche/tier, comptes reliés, top créateurs, croissance du répertoire.
• trouve-ka : pages indexées, domaines, rythme de crawl (indexées/h), erreurs, file frontier, tendances si les requêtes sont journalisées.
• api-ka : appels par endpoint/jour/heure, latences moyennes + p95, taux d'erreur, top endpoints, uptime (données des middlewares de logging + runs).
• Transverse (tous) : volume total agrégé + croissance, connecteurs actifs et éléments ajoutés/mis à jour par période (journaux de sync), complétude/ fraîcheur moyenne des fiches quand mesurable. Trafic web : seulement si des journaux d'accès existent — sinon état vide propre.

# 5. Ajouter une métrique / un graphique / une plateforme

1 métrique = 1 entrée kpis[] ou series[] côté API (requête SQL agrégée + cache) — le front la rend automatiquement. 1 plateforme = implémenter les 2 endpoints du contrat + une page /stats montée sur les composants du kit + kapdf.py (ou gabarit pdfkit) branché sur le même JSON de dashboard.