# 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` : ```typescript 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`: ```typescript 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 : ```typescript // 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) : ```typescript 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** : ```typescript // 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) - [x] Subtask 4.1 : Tests ajoutés dans `src/server/services/email.test.ts` (Vitest) - [x] 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}` - [x] Subtask 4.3 : Test : `RESEND_API_KEY` absent → `console.log` mock appelé, pas d'erreur - [x] Subtask 4.4 : Test : `resend.emails.send` retourne `{ error: {...} }` → `throw new Error` avec message - [x] Subtask 4.5 : Tests ajoutés dans `src/server/api/routers/idea.submit.test.ts` (Vitest) - [x] Subtask 4.6 : Test : `submit` avec `contactEmail` configuré → `sendNewIdeaNotificationEmail` appelé avec `transformateurEmail = contactEmail` - [x] Subtask 4.7 : Test : `submit` avec `contactEmail = null` → `sendNewIdeaNotificationEmail` appelé avec `transformateurEmail = owner.email` - [x] Subtask 4.8 : Test : `submit` avec `contactEmail = null` et `owner.email = null` → `sendNewIdeaNotificationEmail` non appelé - [x] 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) :** ```typescript // 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é :** ```html

Bonjour,

Une nouvelle idée a été soumise dans votre workspace {workspaceName}.

Voir l'idée dans le dashboard →

- AImpact Hub

``` **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é)