# Catalogue d'événements

Défini dans `packages/analytics/src/core/events.ts`. Les noms et les charges utiles sont vérifiés
**à la compilation**, puis validés **à l'exécution** par Zod avant tout envoi.

C'est le seul fichier propre au projet : pour réutiliser les paquets ailleurs, on le remplace. Aucun
adaptateur ne connaît un nom d'événement.

| Événement               | Version | Propriétés                         | Émis par                             |
| ----------------------- | :-----: | ---------------------------------- | ------------------------------------ |
| `page_viewed`           |    1    | `path`, `locale`                   | `PageTracker` (intégration)          |
| `search_performed`      |    1    | `outcome`, `resultCount`, `locale` | À brancher sur la recherche          |
| `outbound_link_clicked` |    1    | `target`, `fromSection`            | À brancher sur `OutboundLinkTracker` |
| `record_viewed`         |    1    | `kind`, `recordId`, `locale`       | Fiches hors personnes                |
| `feature_used`          |    1    | `feature`, `surface?`              | Libre                                |

Les cinq sont câblés depuis le 27/10/2026, chacun depuis **un seul point d'appel** partagé avec
les compteurs Prometheus (`src/features/analytics/events.ts`) :

| Événement               | Où il est émis                                                           |
| ----------------------- | ------------------------------------------------------------------------ |
| `page_viewed`           | `PageTracker`, dans la mise en page                                      |
| `search_performed`      | `PagefindSearch`, au même endroit que l'envoi vers `/api/telemetry`      |
| `outbound_link_clicked` | `OutboundLinkTracker`, avec la section d'origine en plus de la catégorie |
| `record_viewed`         | Fiches de structure, projet, groupe et thématique — **jamais personne**  |
| `feature_used`          | Usage réel des filtres de liste                                          |

`record_viewed` n'est pas émis sur les fiches de personnes : enregistrer quels chercheurs sont
consultés dépasse ce que l'ADR 006 autorise, et la DPO ne s'est pas prononcée.

## Ce que le catalogue interdit volontairement

Le vocabulaire est **fermé**, dans la continuité de la route `/api/telemetry` existante :

- aucun terme de recherche : `search_performed` ne porte que l'issue et le nombre de résultats ;
- aucune URL complète ni query string ;
- `recordId` est un identifiant **public** de structure (numéro RNSR), jamais un identifiant de
  personne ;
- `fromSection` et `surface` sont des énumérations, pas du texte libre, pour borner la cardinalité.

## Versionner un schéma

`eventVersion` accompagne chaque envoi. L'incrémenter dès qu'un changement casse la compatibilité :
propriété retirée, type modifié, sémantique différente. Ajouter une propriété facultative ne la
change pas.

## Déduplication

`eventId` est un identifiant unique par événement. Les fournisseurs qui savent dédupliquer peuvent
s'en servir. La livraison reste « au mieux » : ni Umami ni Matomo ne garantissent l'unicité.

## Ajouter un événement

1. Déclarer le schéma dans `EVENT_SCHEMAS`, avec sa version.
2. Le documenter ici, en indiquant qui l'émet.
3. Vérifier que les propriétés respectent les interdits ci-dessus.
4. L'appeler via `useTrackEvent()` côté navigateur, ou le client serveur.

Aucune modification d'adaptateur n'est nécessaire.