Temps réel (Convex)

Puwapi pousse les mises à jour aux interfaces en temps réel via Convex. C'est une couche d'accélération : l'API REST reste la source de vérité ; le temps réel évite de recharger la page pour voir un changement.

Le flux¶

Module .NET ──POST /<module>/notify──► Convex ──(souscription)──► hub/web
   (après une écriture)     secret HMAC        événement          reload ciblé

1. Après une écriture (création d'item, changement de statut, soumission…), le module notifie Convex sur sa route /<module>/notify, protégée par un secret webhook (<MODULE>_WEBHOOK_SECRET).
2. Convex insère l'événement dans une table dédiée (workEvents, formsEvents, careersEvents, aiEvents…).
3. Le front, abonné via useQuery, reçoit l'événement et déclenche un rechargement ciblé des données concernées.

Événements par module (exemples)¶

Module	Route	Types d'événements
Work	/work/notify	item_created, status_changed, assigned, item_deleted, github_linked, comment_added
Forms	/forms/notify	submission_received
Careers	/careers/notify	application_received, stage_changed, job_published
IA	/ai/notify	inférence terminée (statut)
Loyalty, Cloud, Knowledge…	/<module>/notify	événements propres au module

Côté client¶

Le JWT est transmis aux fonctions Convex comme argument ({ token }), pas via un cookie. Le client ne monte que si l'URL Convex et un jeton sont présents. Modèle type :

const events = useQuery(convexApi.getRecentEvents, { token, limit: 20 });
// à chaque nouvel événement (comparé à un curseur _creationTime), reload()

Confidentialité¶

Les charges utiles envoyées à Convex sont minimales : identifiants + statut, jamais le contenu métier sensible. Le front relit les détails par l'API REST. Exemple pour l'IA : Convex ne reçoit que { requestId, tenantId, featureKey, status }.

À retenir¶

• Le temps réel est optionnel : une intégration serveur peut ignorer Convex et interroger l'API REST (ou un webhook applicatif si disponible).
• Ne considérez jamais un événement Convex comme une donnée faisant autorité : c'est un signal de rafraîchissement.