3-8-notification-email-a-nouvelle-idee-fr32.md 16 KB

Story 3.8 : Notification email à nouvelle idée (FR32)

Status: done

Story

En tant que Transformateur, je veux recevoir une notification email à chaque nouvelle idée soumise dans mon workspace, afin de réagir rapidement et de rester informé sans avoir à me connecter constamment à la plateforme.

Acceptance Criteria

  1. Given une idée est soumise dans mon workspace via le formulaire web (/submit/[workspaceSlug]) When la soumission est validée (idée créée en base) Then je reçois un email de notification contenant :

    • Le département de l'idée
    • Un aperçu de la description du problème (max 200 caractères)
    • L'email du contributeur
    • Un lien direct vers la fiche de l'idée dans le dashboard (/workspace/[workspaceId]/ideas/[ideaId])
  2. Given une idée est soumise dans mon workspace via email (webhook Resend Inbound) When la soumission est validée (idée créée en base) Then je reçois un email de notification identique au cas 1

  3. Given le workspace a un contactEmail configuré When la notification est envoyée Then l'email est adressé à contactEmail

  4. Given le workspace n'a pas de contactEmail configuré When la notification est envoyée Then l'email est adressé à l'email du compte owner (User.email)

  5. Given ni contactEmail ni owner.email ne sont disponibles When la notification est envoyée Then l'envoi est silencieusement ignoré (log côté serveur, pas d'erreur utilisateur)

  6. Given l'envoi de la notification échoue (erreur Resend, réseau, etc.) When l'échec se produit Then l'idée est quand même créée - la notification est fire-and-forget (ne bloque jamais la soumission) And l'erreur est loggée côté serveur : [email] New idea notification failed:

Tasks / Subtasks

  • [x] Task 1 : Ajouter sendNewIdeaNotificationEmail dans src/server/services/email.ts (AC: #1, #2, #3, #4, #5, #6)

    • [x] Subtask 1.1 : Définir l'interface SendNewIdeaNotificationEmailParams :

      export interface SendNewIdeaNotificationEmailParams {
      transformateurEmail: string;
      workspaceName: string;
      workspaceId: string;
      ideaId: string;
      contributorEmail: string;
      department: string;
      problemDescriptionPreview: string; // tronqué à 200 chars côté appelant
      }
      
    • [x] Subtask 1.2 : Implémenter sendNewIdeaNotificationEmail avec le pattern établi (Resend + mock dev)

    • Subject : Nouvelle idée soumise - {workspaceName}

    • HTML : département, aperçu description, email contributeur, lien dashboard

    • Lien : ${baseUrl}/workspace/${workspaceId}/ideas/${ideaId}

    • [x] Subtask 1.3 : Ajouter le mock console.log ([email] New idea notification (mock):) pour dev sans RESEND_API_KEY

  • [x] Task 2 : Modifier src/server/api/routers/idea.ts - procédure submit (AC: #1, #3, #4, #6)

    • [x] Subtask 2.1 : Étendre le select du workspace.findUnique pour inclure contactEmail et owner:

      select: { id: true, name: true, slug: true, contactEmail: true, owner: { select: { email: true } } }
      
    • [x] Subtask 2.2 : Après la création de l'idée (après le fire-and-forget LLM et confirmation email), ajouter :

      // Story 3.8 (FR32) : Notification email Transformateur - fire-and-forget
      const transformateurEmail = workspace.contactEmail ?? workspace.owner.email;
      if (transformateurEmail) {
      void sendNewIdeaNotificationEmail({
      transformateurEmail,
      workspaceName: workspace.name,
      workspaceId: workspace.id,
      ideaId: idea.id,
      contributorEmail: input.contributorEmail.toLowerCase().trim(),
      department: input.department,
      problemDescriptionPreview: input.problemDescription.slice(0, 200),
      }).catch((err: unknown) => {
      console.error("[email] New idea notification failed:", err);
      });
      }
      
    • [x] Subtask 2.3 : Importer sendNewIdeaNotificationEmail depuis ~/server/services/email

  • [x] Task 3 : Modifier src/app/api/webhooks/email/route.ts (AC: #2, #3, #4, #6)

    • [x] Subtask 3.1 : Étendre le select du workspace.findUnique (ligne ~89) :

      select: { id: true, name: true, slug: true, contactEmail: true, owner: { select: { email: true } } }
      
    • [x] Subtask 3.2 : Après la transaction (création idée), déclencher la notification via after() ou fire-and-forget - utiliser after() pour cohérence avec l'enrichissement LLM :

      // Story 3.8 (FR32) : Notification email Transformateur
      const transformateurEmail = workspace.contactEmail ?? workspace.owner.email ?? null;
      if (transformateurEmail) {
      after(async () => {
      try {
        await sendNewIdeaNotificationEmail({
          transformateurEmail,
          workspaceName: workspace.name,
          workspaceId: workspace.id,
          ideaId: idea.id,
          contributorEmail,
          department: "email",
          problemDescriptionPreview: problemDescription.slice(0, 200),
        });
      } catch (err) {
        console.error("[email] New idea notification failed (webhook):", err);
      }
      });
      }
      
    • [x] Subtask 3.3 : Importer sendNewIdeaNotificationEmail depuis ~/server/services/email

  • [x] Task 4 : Tests (AC: #1–#6)

    • Subtask 4.1 : Tests ajoutés dans src/server/services/email.test.ts (Vitest)
    • Subtask 4.2 : Test : appel avec transformateurEmail valide → resend.emails.send appelé avec le bon to, subject, html contenant le lien /workspace/${workspaceId}/ideas/${ideaId}
    • Subtask 4.3 : Test : RESEND_API_KEY absent → console.log mock appelé, pas d'erreur
    • Subtask 4.4 : Test : resend.emails.send retourne { error: {...} } → throw new Error avec message
    • Subtask 4.5 : Tests ajoutés dans src/server/api/routers/idea.submit.test.ts (Vitest)
    • Subtask 4.6 : Test : submit avec contactEmail configuré → sendNewIdeaNotificationEmail appelé avec transformateurEmail = contactEmail
    • Subtask 4.7 : Test : submit avec contactEmail = null → sendNewIdeaNotificationEmail appelé avec transformateurEmail = owner.email
    • Subtask 4.8 : Test : submit avec contactEmail = null et owner.email = null → sendNewIdeaNotificationEmail non appelé
    • Subtask 4.9 : Test : sendNewIdeaNotificationEmail throw → idée quand même retournée (le .catch() absorbe l'erreur)

Dev Notes

Architecture & Décisions techniques

Aucun changement de schéma Prisma requis.

Le modèle Workspace contient déjà :

  • contactEmail String? - email de contact configuré par le Transformateur à la création du workspace (Story 1.3)
  • owner User (relation) → User.email String? - email du compte propriétaire

Destinataire de la notification :

Priorité : workspace.contactEmail → sinon workspace.owner.email → sinon aucun envoi (silencieux).

Justification : contactEmail peut différer de l'email du compte (FR1 - Story 1.3). En B2B, le CDO peut vouloir recevoir les notifications sur un email de service différent de son compte de connexion.

Pattern fire-and-forget (cohérence avec les Stories 2.7 et 3.1) :

// Dans idea.submit (tRPC router)
void sendNewIdeaNotificationEmail({...}).catch((err: unknown) => {
  console.error("[email] New idea notification failed:", err);
});

// Dans webhooks/email/route.ts - utiliser after() pour s'exécuter APRÈS la réponse 200
after(async () => {
  try {
    await sendNewIdeaNotificationEmail({...});
  } catch (err) {
    console.error("[email] New idea notification failed (webhook):", err);
  }
});

Important : La notification ne doit JAMAIS bloquer la création de l'idée. En cas d'échec Resend, l'idée est quand même créée et le formulaire répond correctement.

Contenu de l'email de notification recommandé :

<p>Bonjour,</p>
<p>Une nouvelle idée a été soumise dans votre workspace <strong>{workspaceName}</strong>.</p>
<ul>
  <li><strong>Département :</strong> {department}</li>
  <li><strong>Contributeur :</strong> {contributorEmail}</li>
  <li><strong>Description :</strong> {problemDescriptionPreview}...</li>
</ul>
<p><a href="{ideaUrl}">Voir l'idée dans le dashboard →</a></p>
<p>- AImpact Hub</p>

Pas de notifyNewIdea opt-out : Le PRD (FR32) ne mentionne aucun mécanisme d'opt-out pour cette notification. La notification est envoyée à chaque nouvelle idée, sans condition. (Similaire à autoRelanceEnabled pour la relance J+21 - si un opt-out est demandé, il sera ajouté en correction ou story dédiée.)

Structure des fichiers

Fichier Action Notes
src/server/services/email.ts Modifier - ajouter sendNewIdeaNotificationEmail Ajouter après sendManualRelanceEmail
src/server/api/routers/idea.ts Modifier - procédure submit : étendre workspace select + appel notification Environ ligne 64 (findUnique) et ligne 124 (fire-and-forget email confirmation)
src/app/api/webhooks/email/route.ts Modifier - étendre workspace select + appel notification via after() Environ ligne 89 (findUnique) et ligne 183 (after LLM block)
src/server/services/email.newIdeaNotification.test.ts Créer - tests Vitest pour la fonction email Pattern identique aux tests des autres fonctions email
src/server/api/routers/idea.submit.notifyTransformateur.test.ts Créer - tests Vitest pour l'intégration dans submit Mock sendNewIdeaNotificationEmail

Conventions architecture à respecter

  • Fire-and-forget obligatoire : void fn().catch(...) dans idea.submit - ne jamais await un email dans une mutation tRPC
  • after() dans le webhook : déjà utilisé pour l'enrichissement LLM, cohérent d'utiliser le même mécanisme pour la notification
  • Pas de await dans le webhook après la réponse : after() garantit l'exécution POST réponse 200 (Next.js 15+)
  • Zod input : aucun nouveau input Zod - la notification utilise les données déjà validées dans submit
  • Tests co-localisés : *.test.ts à côté du fichier testé ou dans __tests__/
  • Isolation multi-tenant : aucun risque ici - la notification va vers l'owner du workspace, les données de l'idée proviennent du même workspace

Apprentissages des stories précédentes

Story 3.7 (résumé nouvelles activités) :

  • createWorkspaceProcedure → ctx.workspace contient tous les champs Workspace, y compris contactEmail et owner (si inclus dans le select initial de la procédure)
  • Pattern test Vitest : mocker ctx.workspace pour les procédures workspace

Story 2.7 (confirmation email) :

  • Pattern établi : void sendXxxEmail({...}).catch((err: unknown) => { console.error("...", err); });
  • Dans idea.submit, le workspace est fetché avec select - penser à ajouter contactEmail et owner.email sinon TypeScript error
  • Resend mock en dev : if (!resend) { console.log("[email] ...", {...}); return; }

Story 2.10 (relance J+21) :

  • Le cron route api/cron/relance/route.ts fetchait déjà workspace.name, workspace.slug pour les emails - même pattern à appliquer
  • after() dans le webhook email : utilisé pour l'enrichissement LLM (Story 3.1) - réutiliser pour la notification

Story 3.1 (enrichissement LLM) :

  • webhooks/email/route.ts utilise after() (Next.js 15) pour le fire-and-forget post-réponse
  • La fonction after() est importée depuis next/server : import { after, NextResponse } from "next/server"
  • Avantage : s'exécute APRÈS que le webhook ait répondu 200 à Resend - évite tout timeout côté Resend

Cas limites et comportements attendus

Cas Comportement
contactEmail configuré Notification → contactEmail
contactEmail = null, owner.email défini Notification → owner.email
contactEmail = null, owner.email = null Aucun envoi, pas d'erreur
Resend indisponible Idée créée quand même, erreur loggée, pas de retry
RESEND_API_KEY absent (dev) console.log mock, pas d'envoi réel
Description très longue Tronquée à 200 chars (problemDescription.slice(0, 200)) avant envoi
Idée soumise via email (webhook) Même comportement que via formulaire
Soumission simultanées multiples Une notification par idée, indépendantes

NFR concernés

  • NFR2 : pas d'impact (la notification est fire-and-forget, ne ralentit pas la réponse)
  • NFR9 : Si Resend est indisponible, la soumission reste fonctionnelle - la notification est best-effort
  • NFR14 : isolation workspace - la notification ne concerne que le workspace de l'idée

References

  • [Source: epics.md#Story 3.8 - Notification email à nouvelle idée (FR32)]
  • [Source: prd.md#FR32 - Le Transformateur reçoit une notification email à chaque nouvelle idée soumise]
  • [Source: architecture.md#Services - services/email.ts : invitations, relances, notifications]
  • [Source: architecture.md#Implementation Patterns - fire-and-forget, error handling patterns]
  • [Source: architecture.md#API Boundaries - Route Handlers pour webhooks]
  • [Source: src/server/services/email.ts - pattern Resend, mock dev, sendSubmissionConfirmationEmail, sendManualRelanceEmail]
  • [Source: src/server/api/routers/idea.ts - procédure submit : pattern fire-and-forget LLM + email confirmation (lignes 113–130)]
  • [Source: src/app/api/webhooks/email/route.ts - after() pour LLM (lignes 183–195), workspace select (ligne 89)]
  • [Source: prisma/schema.prisma - model Workspace : contactEmail String?, relation owner User, owner.email String?]
  • [Source: implementation-artifacts/3-7-resume-des-nouvelles-activites-fr28.md - patterns fire-and-forget, createWorkspaceProcedure, tests Vitest]
  • [Source: implementation-artifacts/2-7-confirmation-visuelle-et-email-de-soumission-fr16.md - pattern email confirmation post-soumission]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

  • ✅ Story 3.8 (FR32) implémentée : notification email Transformateur à chaque nouvelle idée soumise
  • ✅ sendNewIdeaNotificationEmail ajoutée dans services/email.ts avec interface, mock dev, et échappement HTML
  • ✅ Intégration dans idea.submit (tRPC) : fire-and-forget avec priorité contactEmail → owner.email
  • ✅ Intégration dans webhooks/email/route.ts : after() pour notification post-réponse
  • ✅ Code review corrigée : escapeHtml définie avant usage (H2), indicateur … pour troncature (M2)
  • ✅ Couverture test renforcée : tests XSS + troncature dans email.test.ts (M1), 3 tests AC #2 dans route.test.ts via mockAfterFn contrôlable (H1)
  • ✅ JSDoc mis à jour dans route.ts et idea.ts pour référencer Story 3.8 (FR32) (L1, L2)
  • ✅ 36 tests sur 3 fichiers passent - total 352 tests (hors seed.test.ts pré-existant)

Change Log

  • 2026-02-28 : Implémentation complète Story 3.8 (FR32) - notification email Transformateur à nouvelle idée
  • 2026-02-28 : Code review corrigée - H1 (test AC#2 webhook), H2 (escapeHtml ordre), M1 (tests XSS), M2 (ellipse troncature), L1/L2 (JSDoc)

File List

  • aimpact-hub/src/server/services/email.ts (modifié)
  • aimpact-hub/src/server/services/email.test.ts (modifié)
  • aimpact-hub/src/server/api/routers/idea.ts (modifié)
  • aimpact-hub/src/server/api/routers/idea.submit.test.ts (modifié)
  • aimpact-hub/src/app/api/webhooks/email/route.ts (modifié)
  • aimpact-hub/src/app/api/webhooks/email/route.test.ts (modifié)