Notifications

Périmètre : notifications in-app, email transactionnel, SMS transactionnel, templates configurables par organisation, préférences utilisateur, queues persistantes avec retry exponentiel, webhooks providers (Brevo, OVH SMS…).

Vocabulaire & entités

Le modèle complet est dans docs/04-data-model.md §12. Le type de notification est un enum Prisma NotificationKind, pas une chaîne libre.

Types de notification (NotificationKind)

MENTION                COMMENT_REPLY
INVOICE_ISSUED         INVOICE_PAID
OT_ASSIGNED            LEASE_AFFAIR_STATUS
GENERIC
CRM_MISSED_CALL        CRM_ACTION_OVERDUE      CRM_ACTION_ASSIGNED
CRM_PROSPECT_PROMOTED
RATING_REQUESTED       RATING_VALIDATED        RATING_EXPIRING       RATING_NO_GO_ON_DEAL

Écrans & préférences

Modèle de données (points clés)

• Notification : créée en in-app (createNotification) puis les jobs d'envoi email/SMS sont enqueués selon les préférences. Champs de tracking : emailMessageId, smsMessageId, emailStatus. Index (recipientUserId, readAt, createdAt).
• NotificationPreference : clé unique (userId, kind, channel), booléen enabled.
• L'envoi différé passe par la table générique Job (pas de table EmailQueue / SmsQueue) : jobs notification:send-email et notification:send-sms, retry avec backoff exponentiel géré par jobs.ts.

API

Les routes /api/account/* n'exigent qu'une session authentifiée — chaque utilisateur ne voit et ne modifie que ses propres notifications et préférences.

Routes implémentées

Routes cible (non implémentées)

curl -s -X PATCH "$API/api/account/notification-preferences" \
  -H "Content-Type: application/json" -H "Cookie: $SESSION" \
  -d '{"kind":"INVOICE_ISSUED","channel":"SMS","enabled":false}'

{ "kind": "INVOICE_ISSUED", "channel": "SMS", "enabled": false }

Workflows

Émission d'une notification

Le service notification.service.ts expose createNotification(input), appelé par les autres services lors de mutations sensibles.

await createNotification({
  organizationId,
  recipientUserId: 'usr_...',
  kind: 'LEASE_AFFAIR_STATUS',
  title: 'Affaire mise à jour',
  body: 'Le contrat LLD-2026-000123 a changé de statut.',
  targetUrl: `/workspace/lease-affairs/${affairId}`,
  payload: { affairId },
})

Flux interne :

1. Crée la Notification in-app (canal incompressible).
2. dispatchChannelJobs : charge les NotificationPreference (userId, kind) et, pour chaque canal enabled :
   • EMAIL → enqueueJob('notification:send-email', { notificationId }).
   • SMS → enqueueJob('notification:send-sms', { notificationId }).

Poller de jobs

Il n'y a pas de cron dédié aux emails : tous les jobs (dont notification:send-email / notification:send-sms) passent par la table générique Job, traitée par le poller toutes les 10 s (processDueJobs, jobs.ts).

Pour chaque job dû :
  1. Exécute le handler (sendNotificationEmail / sendNotificationSms)
  2. Succès → met à jour Notification.emailMessageId / emailStatus = 'sent'
  3. Échec + attempt < maxAttempts → reschedule avec backoff exponentiel
  4. Échec + attempt >= maxAttempts → FAILED + alertJobFailure

Providers email (EMAIL_PROVIDER)

Providers SMS

SMS via server/lib/sms.ts selon la configuration d'environnement.

Tracking livraison (webhook entrant)

• POST /api/webhooks/brevo/track : route publique, vérifiée par un token simple en en-tête x-brevo-token (comparé à BREVO_WEBHOOK_SECRET, fail-closed si non configuré). Événements delivered / opened (clicked mappé sur opened) / bounced → mise à jour de Notification.emailStatus.

Règles métier

• IN_APP toujours créée : la Notification in-app est le canal incompressible ; les canaux EMAIL/SMS dépendent des NotificationPreference.
• Pause utilisateur : un utilisateur peut suspendre ses notifications jusqu'à une date (PATCH /api/account/notifications-pause).
• RGPD : opt-out clair en footer pour les emails non strictement transactionnels.