# ADR-005 : Laravel Pulse en staging pour l'observabilité applicative

**Statut :** Accepté (implémentation en tâche de suivi — non codée à la date de cet ADR)
**Date :** 2026-08-04
**Contexte :** `gestionstock` (Laravel), staging et production

---

## Contexte

Un audit WES complet (2026-08-04) a constaté qu'aucun outil d'observabilité n'est installé sur `gestionstock` — ni Telescope, ni Pulse, ni équivalent, malgré une référence résiduelle et inutilisée à `TELESCOPE_ENABLED` dans `phpunit.xml`. `checklists/performance.md` et `standards/laravel.md` (WES) supposent la disponibilité de Telescope/Pulse pour vérifier les seuils de performance (≤10 requêtes/requête HTTP, ≤20ms par requête, absence de N+1), mais rien ne permet aujourd'hui de le vérifier autrement que par lecture de code ou par des tests unitaires ciblés (ex. `OrderProcessingServiceTest::pricer_preloads_once_and_prices_multiple_lines_without_further_queries`).

WES ADR-014 (`welely-engineering-system/decisions/014-observability-pulse-staging.md`) documente déjà cette même décision, mais son périmètre déclaré est explicitement `studio-welely-backend` — il ne couvre pas `gestionstock`. Ce projet a son propre historique d'incidents de performance (N+1 de pricing corrigé lors de cet audit, critique #2) qui justifie la même décision, indépendamment de l'autre projet.

## Décision

**Installer `laravel/pulse` sur `gestionstock`, activé uniquement en environnement staging**, avec la même règle que WES ADR-014 : jamais en production par défaut, pour ne pas ajouter de surface d'écriture continue sur la base de données de production sans décision explicite ultérieure.

Pulse est choisi plutôt que Telescope comme outil par défaut : il est conçu pour tourner en continu avec un coût de stockage et de performance minimal (agrégation périodique plutôt que capture exhaustive), adapté à un usage « toujours allumé » en staging sur une application multi-tenant à fort volume de requêtes (POS, dashboard). Telescope reste disponible en installation ponctuelle et locale (`composer require --dev laravel/telescope`) pour une session de debug approfondie.

## Alternatives Considérées

### Étendre le périmètre de WES ADR-014 à tous les projets Laravel Welely

Rejetée : WES ADR-014 documente une décision prise pour `studio-welely-backend` avec son propre contexte (taille du projet, absence d'incident spécifique). `gestionstock` a des caractéristiques différentes (SaaS multi-tenant, volume de requêtes POS, historique d'incidents de performance déjà documenté dans ADR-004) qui justifient sa propre décision plutôt qu'un héritage silencieux d'un ADR écrit pour un contexte différent.

### Laravel Telescope en continu

Rejeté comme outil par défaut, mêmes raisons que WES ADR-014 : coût de stockage et de requête disproportionné pour un usage permanent face à une simple détection de dérives (requêtes lentes, jobs en échec, exceptions récurrentes).

### Statu quo (aucun outil)

Rejeté — c'est précisément le constat de cet audit : sans outil, les seuils de `checklists/performance.md` ne sont vérifiables qu'en théorie. Le N+1 de pricing corrigé lors de cet audit (critique #2) aurait été détectable en quelques minutes via Pulse plutôt que par lecture de code.

## Conséquences

- `composer require laravel/pulse`, migration Pulse, et route `/pulse` protégée par un Gate restreint aux comptes admin/superadmin (`Gate::define('viewPulse', ...)` dans `AppServiceProvider`).
- Activation conditionnée à `app()->environment('staging')` — désactivée par défaut ailleurs, y compris en production, tant qu'une décision explicite n'étend pas son usage.
- **Non implémenté à la date de cet ADR** — tâche de suivi à planifier séparément (installation + configuration + Gate d'accès), hors du périmètre des corrections déjà appliquées lors de cet audit.

## Quand Réviser

- Si l'équipe constate que Pulse ne donne pas assez de détail pour diagnostiquer un incident récurrent — envisager d'activer Telescope ponctuellement en parallèle plutôt que de l'abandonner.
- Si le volume de trafic ou la criticité de l'application augmentent significativement — réévaluer l'activation de Pulse en production avec un TTL de rétention court.