DOCS/v2/stats-screen-plan.md

Écran Statistiques — refonte

Audit du code réel + décisions du 2026-08-07. Refonte implémentée le 2026-08-07 — voir « État d'implémentation » en fin de document. Maquette : https://claude.ai/code/artifact/052fe8f3-0288-4847-b63f-4c7de06068ec Fichier concerné : manager-app/lib/Screens/Statistics/statistics_screen.dart

---

Les sept défauts de l'écran actuel

(État avant refonte — les numéros de ligne renvoient à l'ancienne version de 625 lignes.)

Ce sont des problèmes d'interface, pas de données : StatsSummaryDTO contient déjà tout ce qu'il faut.

#	Défaut	Où
1	Libellés de sections tronqués à 8 caractères — title.substring(0, 8) sur des barres verticales. « Histoire du fort » → « Histoir… ». Le graphe le plus important est illisible sur son propre sujet, et c'est structurel : des barres verticales n'ont pas la place pour des titres	:368
2	Deux des quatre KPI n'en sont pas — « Top app » et « Top langue » affichent une valeur catégorielle unique, que les deux anneaux plus bas montrent en mieux, avec la distribution	:199-201
3	Chips de canaux générées depuis AppType.values sans filtrer sur ce que l'instance possède. Un client Essentiel voit une chip « Mobile » qu'il n'a pas, clique, tombe sur l'écran vide	:130-136
4	Deux mécaniques de filtre empilées — SegmentedButton pour la période, ChoiceChip pour le canal, sur deux lignes de poids visuel différent, pour deux filtres de même nature	:101-138
5	Deux anneaux côte à côte — un donut se lit mal dès trois parts, et les langues peuvent en avoir dix	:322-326
6	Palette qui se répète — _chartColors[i % length] sur six teintes : au-delà de six langues, deux langues reçoivent la même couleur. Et ce sont six nuances du même bleu, donc un dégradé utilisé comme palette catégorielle	:394-401, :428
7	Aucune hiérarchie, aucun export — KPI, courbe, graphes, tables : tout est une Card de poids égal empilée. Rien ne dit par où commencer, et il n'y a pas de bouton de rapport	:168-181

---

Décisions de refonte

Le titre et la période

L'écran s'appelle « Fréquentation », pas « Statistiques » — c'est la question que se pose le client. La période est écrite en toutes lettres sous le titre (« Du 1ᵉʳ au 31 août 2026 ») : aujourd'hui elle n'existe que dans le filtre, donc une capture d'écran ne dit pas de quoi elle parle.

Un bandeau « à retenir »

Deux phrases en langage naturel au-dessus des chiffres. C'est ce qui fait qu'un client qui ouvre l'écran trois secondes en retire quelque chose. Les chiffres bruts ne se commentent pas tout seuls.

Généré côté backend à partir des mêmes agrégats (variation vs période précédente, contenu dominant, canal émergent). Pas d'appel LLM nécessaire pour la V1 — des règles suffisent.

Quatre vrais KPI, tous avec une évolution

Un nombre sans comparaison ne veut rien dire. Chaque KPI porte sa variation vs période précédente.

Multi-canal	Mono-canal
Visites · Durée moyenne · Contenus par visite · Part du guide vocal	Visites · Durée moyenne · Contenus par visite · Visiteurs uniques

Barres horizontales partout, une seule teinte

• Plus aucun anneau : au-delà de trois parts, l'œil compare mal des angles.
• Libellés complets, jamais tronqués.
• Une seule teinte : toutes les barres mesurent la même chose (un nombre de visites), c'est la longueur qui porte l'information. Colorer chaque barre suggérerait une distinction inexistante et deviendrait illisible dès sept catégories.
• Le problème de palette qui se répète disparaît de lui-même.

Une seule barre de filtres

Période et canal sur la même ligne, même traitement visuel. Chaque canal porte son volume (Guide vocal · 463) : on voit où il y a de la matière avant de cliquer, au lieu de découvrir un écran vide.

Règle mono-canal — importante

Compter les ApplicationInstance réellement actives de l'instance. Une seule → masquer le filtre « Canal », la carte « Canaux », et remplacer le KPI vocal par « Visiteurs uniques ». Deux ou plus → afficher, avec uniquement les canaux existants.

C'est la situation courante aujourd'hui : les clients ont soit une app mobile, soit une borne, rarement les deux. Ça deviendra multi-canal avec un client comme Visit Namur (borne + mobile + vocal).

Un graphe à une seule barre à 100 % ne dit rien — et un écran qui ne s'adapte qu'à moitié se voit immédiatement. Le bandeau « à retenir » change aussi de deuxième phrase en mono-canal : sans canaux à comparer, l'information intéressante est ailleurs.

La courbe

Aire simple, une seule série, avec :

• bandes claires sur les week-ends — la dent de scie devient lisible sans légende à décoder
• pic cerclé et nommé sous le graphe
• survol : trait vertical + valeur du jour

Pas de multi-séries par canal : quatre lignes emmêlées répondent mal à « est-ce que ça monte ? ». La répartition par canal est déjà donnée par les barres.

Le rapport comme bloc, pas comme bouton

Le client voit le document qu'il va envoyer, avec son sommaire : fréquentation, contenus, canaux dont le vocal. C'est ce qui transforme l'écran en livrable — et c'est l'argument subside.

Décidé le 2026-08-07 : v1 = bouton à la demande uniquement, généré côté client (paquet pdf Dart, déjà présent). L'envoi mensuel automatique passe en v2 et se fera côté backend — voir plan-import-ia-stats-subsides.md §1.

Le sommaire annoncé par le bloc a été corrigé pour ne promettre que ce qui existe : la puce « questions posées au guide IA » et la mention « parcours terminés » ont été retirées, faute de données (voir ci-dessous).

---

Onglet / canal « Vocal »

Moins de travail qu'il n'y paraît : AppType.Voice existe déjà dans le modèle, et AiChatRequest.IsVoice distingue déjà les interactions vocales.

• ✅ Vérifié le 2026-08-07 : VisitEvent porte bien l'AppType (StatsController.cs:52-65 à l'écriture, :114 et :191-195 à la lecture), et Voice est bien la valeur 4 de l'enum backend (ApplicationInstance.cs:106-113). Le canal vocal s'ajoute donc sans changement backend — c'est fait côté écran. Seul manquait 'Voice' dans AppTypeName côté client généré, corrigé.
• À afficher : volume, ce qui a été réellement écouté (contenus déclenchés à la voix, POI atteints, durée d'écoute), part dans l'usage total.
• À inclure dans l'export PDF : « X % de nos visiteurs ont utilisé le guide vocal » est un argument de renouvellement de subside.

---

Langue de l'interface

Toutes les chaînes passent par AppLocalizations (FR / NL / EN) — la langue du gestionnaire, distincte de celle des contenus. L'écran actuel le fait déjà correctement ; ne pas régresser.

---

Ordre d'implémentation

#	Tâche	Statut	Note
1	Barres horizontales à la place des barres verticales + anneaux	✅	Corrige les défauts 1, 5 et 6 d'un coup
2	Barre de filtres unifiée, canaux filtrés sur l'existant + volumes	✅	Défauts 3 et 4
3	Règle mono-canal (masquage filtre + carte + KPI de substitution)	✅	Voir la réserve « visiteurs uniques » ci-dessous
4	KPI revus, avec variation vs période précédente	✅	Défaut 2 — sans changement backend, voir ci-dessous
5	Bandeau « à retenir » (règles, pas de LLM)	✅	Généré côté client, voir ci-dessous
6	Courbe en aire + bandes week-end + survol	✅	—
7	Bloc rapport + export PDF	✅	Bouton à la demande, PDF généré côté client. L'envoi mensuel est en v2 — voir ci-dessous
8	Canal vocal	✅	Filtre, carte Canaux et KPI de part vocale. Le détail « ce qui a été écouté » reste à faire

---

État d'implémentation — 2026-08-07

Écran refondu : manager-app/lib/Screens/Statistics/statistics_screen.dart. Les sept défauts sont corrigés. Trois écarts assumés par rapport au plan et à la maquette, tous documentés ici.

1. La comparaison de période se fait côté client, pas côté backend

Le plan supposait un agrégat de période précédente à ajouter au backend. Inutile : statsGetSummary prend déjà from/to, donc l'écran appelle deux fois le même endpoint — période courante et période précédente de même durée. Trois requêtes au maximum (courante, précédente, et « tous canaux » quand un filtre de canal est actif), lancées en parallèle.

Garde importante : le backend rogne from sur StatsHistoryDays (StatsController.cs:102-107) sans le signaler. Une période précédente hors historique reviendrait tronquée, et la variation serait fausse sans qu'on le voie. L'écran ne demande donc la période précédente que si StatsHistoryDays == 0 || StatsHistoryDays >= 2 × période ; sinon les KPI s'affichent simplement sans variation. Même logique sur les chips de période : celles qui dépassent l'historique du plan sont désactivées.

2. Le bandeau « à retenir » est généré côté client

Le plan le voulait côté backend. Côté client c'est plus simple et mieux localisé : les phrases passent par AppLocalizations, donc elles suivent la langue du gestionnaire (FR/NL/EN) sans que le backend ait à la connaître. Les règles sont les mêmes :

• phrase 1 — variation vs période précédente (seuil de stabilité : ±3 %), ou à défaut le volume et la moyenne par jour ;
• phrase 2 — multi-canal : la part du guide vocal si elle existe, sinon le canal dominant ; mono-canal (ou écran déjà filtré sur un canal) : le contenu phare et sa part des consultations.

À déplacer côté backend le jour où l'export PDF aura besoin des mêmes phrases.

3. « Visiteurs uniques » n'existe pas dans le modèle de données

Le plan prévoyait ce KPI en substitution du vocal en mono-canal. Il n'est pas calculable : TotalSessions est le nombre de SessionId distincts (StatsController.cs:121), et VisitEvent ne porte aucun identifiant de visiteur au-delà de la session. « Visiteurs uniques » afficherait exactement le même nombre que « Visites », juste à côté — c'est-à-dire le défaut n° 2 réintroduit.

Le quatrième KPI est donc « Contenus consultés » (total des SectionView de la période) quand il n'y a pas de canal vocal. C'est un nombre distinct des trois autres, avec sa propre variation. Le vrai « visiteurs uniques » demanderait un identifiant de device persistant sur VisitEvent — décision produit, pas d'interface.

4. L'export PDF est côté client, et c'est un choix de périmètre

(Décidé le 2026-08-07, livré le même jour.)

v1 = le bouton seul. Le PDF est construit dans le navigateur avec le paquet pdf Dart — déjà dans le pubspec, déjà utilisé par PDFHelper pour les QR codes. Rien côté backend : pas de StatsService à extraire, pas d'endpoint, pas de libfontconfig1 à ajouter au Dockerfile. L'écran a déjà tous les agrégats en main.

v2 = l'envoi mensuel automatique, qui lui doit être backend : personne n'a son navigateur ouvert le 1ᵉʳ du mois à 6 h. C'est là que QuestPDF + Hangfire reprennent leur sens, et c'est aussi là que se posent les trois questions qu'on a évitées en v1 : la config des destinataires, la fréquence, et une méthode d'envoi avec pièce jointe (IEmailService n'en a aucune — ses dix méthodes sont des templates figés).

Conséquences de l'implémentation côté client :

• Le PDF et l'écran partagent les mêmes valeurs calculées. _kpis(), _takeawaySentences(), _contentBars(), _advancedTables() alimentent les deux. Un chiffre ne peut pas diverger entre ce que le client voit et ce qu'il envoie à sa commune.
• La couleur et le logo viennent du premier canal actif, l'app mobile en priorité. Instance ne porte que Name : ni logo ni couleur. Le logo est lu par HTTP depuis Firebase Storage — sans en-tête CORS sur le bucket, le navigateur refuse les octets et la page de garde retombe sur le seul nom de l'instance. À traiter avec v2/media-storage-plan.md (le gsutil cors set y a sa place).
• Un test couvre la génération (test/statistics_report_test.dart, 4 cas). Il a immédiatement attrapé deux plantages : hauteur infinie sur la rangée de KPI (CrossAxisAlignment.stretch sous un MultiPage sans contrainte verticale, et le paquet pdf n'a pas d'IntrinsicHeight), et un NaN sur une série d'un seul point. Les deux auraient explosé au premier clic.

5. Deux promesses du bloc rapport n'avaient aucune donnée derrière

Le sommaire de la maquette annonçait quatre choses. Deux n'étaient adossées à rien :

Promesse	État réel	Suite
« parcours terminés »	Aucun VisitEventType ne couvre l'achèvement d'un parcours guidé (VisitEvent.cs:48-60), et rien ne le trace côté visitapp	À ajouter : valeur d'enum + appel track() dans GuidedPathContentProgressionPage / GuidedPathMapProgressionPage. Pas de plan existant — c'est ici qu'il faut le noter
« ce que vos visiteurs ont demandé au guide IA »	Table VisitorQuestion inexistante, et VisitEventType.AssistantMessage existe dans l'enum mais personne ne l'émet (10 appels à track(), aucun pour l'assistant)	Spécifié dans guide-ia-screen-plan.md §7, part avec la migration v3

Les deux puces ont été retirées du bloc et remplacées par ce que le PDF contient réellement. La quatrième puce (POI, quiz, jeux, QR) ne s'affiche que si HasAdvancedStats.

Autres points

• Le bouton d'export du bandeau supérieur de la maquette n'a pas été repris : il faisait doublon avec le bloc rapport, qui montre le document plutôt que de le promettre.
• Courbe sur série continue : visitsByDay n'émet que les jours qui ont des événements. L'écran reconstruit la série jour par jour de from à to en comblant les trous à zéro — sans ça les bandes de week-end tomberaient à côté et la pente serait fausse. Les bandes de week-end ne sont dessinées qu'en deçà de 62 jours ; au-delà c'est du bruit.
• Statistiques avancées : le backend vide LanguageDistribution, POI, quiz, jeux, articles, menu et QR quand HasAdvancedStats est faux (StatsController.cs:359-369). Les cartes correspondantes se masquent d'elles-mêmes et le bloc « plan Premium » prend la place — il est passé par AppLocalizations, il était en dur en français.
• Nouveau chantier possible : DayStatDTO ne porte que Mobile et Tablet en plus du total. Web, VR et vocal n'ont pas leur ventilation quotidienne. Sans importance ici (la courbe est mono-série par décision), mais à corriger si une ventilation par canal dans le temps devient nécessaire.

---

Liens

• guide-ia-screen-plan.md — l'onglet « Ce que demandent vos visiteurs » suit les mêmes principes de forme
• plan-import-ia-stats-subsides.md §1 — export PDF des stats