2-5-soumission-didee-par-email-fr15.md 16 KB

Story 2.5 : Soumission d'idée par email (FR15)

Status: done

Story

En tant que Contributeur, je veux soumettre une idée par email à une adresse dédiée au workspace, afin de contribuer sans passer par le formulaire web.

Acceptance Criteria

  1. Given le workspace a une inbox email dédiée dont l'adresse est affichée dans le dashboard (section Settings ou Contributors) When je consulte le dashboard en tant que Transformateur Then je vois l'adresse email dédiée du workspace au format ideas-{workspaceSlug}@{INBOUND_EMAIL_DOMAIN} And un bouton "Copier l'adresse" permet de copier cette adresse facilement

  2. Given le contributeur envoie un email à l'adresse inbox dédiée When l'email arrive chez Resend Inbound Then Resend appelle le webhook POST /api/webhooks/email avec le payload email.received And une idée est créée dans le backlog du workspace en moins de 15 minutes (NFR6)

  3. Given le webhook reçoit un payload Resend email.received When le handler traite l'email Then la signature Resend est vérifiée via resend.webhooks.verify() avant tout traitement (headers svix-id, svix-timestamp, svix-signature) And si la signature est invalide → réponse 401 Unauthorized, aucune idée créée

  4. Given la signature est valide When le handler extrait les données de l'email Then le slug du workspace est extrait du champ to (format ideas-{workspaceSlug}@{domain}) And si le workspace n'est pas trouvé en base → réponse 404, aucune idée créée And si le workspace est trouvé → le corps de l'email est récupéré via l'API Resend (resend.emails.receiving.get({ emailId }))

  5. Given le corps de l'email est récupéré When l'idée est créée en base Then les champs sont remplis comme suit :

    • contributorEmail : adresse email de l'expéditeur (champ from, parsé pour extraire l'email seul)
    • problemDescription : corps de l'email en texte brut (text)
    • department : "email" (valeur fixe pour distinguer les soumissions email)
    • estimatedImpact : MODERE (défaut pour soumissions email)
    • frequency : PONCTUELLE (défaut pour soumissions email)
    • workspaceId : résolu depuis le slug du workspace And si un Contributor existe dans ce workspace avec le même email → contributorId est défini et son statut passe à SUBMITTED
  6. Given l'idée est créée avec succès When le webhook répond Then réponse 200 OK avec { success: true, ideaId: "..." } And aucune idée en doublon n'est créée si le même webhook est rejoué (idempotence via message_id Resend)

Tasks / Subtasks

  • [x] Task 1 : Affichage de l'inbox email dans le dashboard (AC: #1)

    • Subtask 1.1 : Ajouter une variable d'environnement INBOUND_EMAIL_DOMAIN dans .env.example avec une valeur de test (ex. cool-hedgehog.resend.app)
    • Subtask 1.2 : Créer une fonction utilitaire getWorkspaceInboxEmail(slug: string): string dans src/lib/utils.ts (ou src/lib/email-inbox.ts) : return \ideas-\${slug}@\${process.env.INBOUND_EMAIL_DOMAIN ?? 'resend.app'}``
    • Subtask 1.3 : Ajouter dans la page settings ou contributors du workspace (src/app/(dashboard)/workspace/[workspaceId]/settings/page.tsx) une section "Recevoir des idées par email" avec l'adresse inbox affichée et un bouton "Copier" (toast de confirmation)
  • [x] Task 2 : Route webhook POST /api/webhooks/email (AC: #2, #3, #4, #5, #6)

    • Subtask 2.1 : Créer src/app/api/webhooks/email/route.ts - route POST Next.js App Router
    • [x] Subtask 2.2 : Vérification de la signature Resend dans le handler :

      const payload = await req.text(); // lire le corps brut AVANT json()
      const headers = {
      id: req.headers.get('svix-id') ?? '',
      timestamp: req.headers.get('svix-timestamp') ?? '',
      signature: req.headers.get('svix-signature') ?? '',
      };
      const event = resend.webhooks.verify({ payload, headers, webhookSecret: process.env.RESEND_WEBHOOK_SECRET! });
      
    • [x] Subtask 2.3 : Filtrer uniquement event.type === 'email.received' - ignorer les autres types (répondre 200 sans traitement)

    • [x] Subtask 2.4 : Extraire le slug depuis le champ to - parser data.to[0] pour obtenir la partie locale avant @, puis retirer le préfixe ideas- : slug = to.split('@')[0].replace('ideas-', '')

    • [x] Subtask 2.5 : Chercher le workspace par slug avec ctx.db.workspace.findUnique({ where: { slug } }) - si non trouvé → NextResponse.json({ error: 'Workspace not found' }, { status: 404 })

    • [x] Subtask 2.6 : Idempotence - vérifier si une idée avec messageId = data.message_id existe déjà en base avant création (voir Task 3 pour le champ messageId)

    • [x] Subtask 2.7 : Appel API Resend pour récupérer le corps de l'email :

      const emailContent = await resend.emails.receiving.get({ emailId: data.email_id });
      const bodyText = emailContent.data?.text ?? emailContent.data?.html ?? data.subject ?? '';
      
    • [x] Subtask 2.8 : Créer l'idée en base (transaction Prisma) - voir champs AC #5 ; matching contributeur par email comme dans idea.router.submit

    • [x] Subtask 2.9 : Retourner NextResponse.json({ success: true, ideaId: idea.id }, { status: 200 })

  • [x] Task 3 : Migration Prisma pour idempotence email (AC: #6)

    • Subtask 3.1 : Ajouter le champ emailMessageId String? @unique sur le modèle Idea dans prisma/schema.prisma - pour stocker le message_id Resend et éviter les doublons sur replay webhook
    • Subtask 3.2 : Générer la migration SQL : prisma migrate dev --name add_idea_email_message_id
  • [x] Task 4 : Variables d'environnement (AC: #2, #3)

    • Subtask 4.1 : Ajouter RESEND_WEBHOOK_SECRET dans .env.example (obligatoire en production)
    • Subtask 4.2 : Vérifier que RESEND_API_KEY est déjà documenté dans .env.example (déjà présent depuis Story 2.1)
  • [x] Task 5 : Tests (AC: #2, #3, #4, #5, #6)

    • Subtask 5.1 : Créer src/app/api/webhooks/email/route.test.ts (ou __tests__/api/webhooks/email.test.ts) avec Vitest - mocker resend.webhooks.verify, resend.emails.receiving.get, et ctx.db
    • Subtask 5.2 : Test : signature invalide → 401
    • Subtask 5.3 : Test : workspace non trouvé → 404
    • Subtask 5.4 : Test : email valide → idée créée avec les bons champs (contributorEmail, problemDescription, department = "email", estimatedImpact = MODERE, frequency = PONCTUELLE)
    • Subtask 5.5 : Test : idempotence - deuxième appel avec même message_id → 200 sans doublon
    • Subtask 5.6 : Test : matching contributeur existant → contributorId défini, statut SUBMITTED

Dev Notes

Architecture & décisions techniques

Resend Inbound - comportement critique à connaître :

  • Le payload webhook email.received ne contient PAS le corps de l'email - uniquement les métadonnées (from, to, subject, message_id, liste des pièces jointes)
  • Le corps (texte + HTML) doit être récupéré séparément via resend.emails.receiving.get({ emailId }) après réception du webhook
  • Source : Resend Inbound Docs

Sécurité webhook - NE PAS OUBLIER :

  • La vérification de signature utilise la librairie Svix (embarquée dans le SDK Resend)
  • Il faut lire le corps de la requête en texte brut (req.text()) AVANT de le parser en JSON pour la vérification - sinon la signature sera invalide
  • RESEND_WEBHOOK_SECRET est configuré dans le dashboard Resend lors de la création du webhook
  • Sans cette vérification, n'importe qui pourrait appeler le webhook et créer des idées fictives

Routage workspace par email :

  • L'adresse inbox = ideas-{workspaceSlug}@{INBOUND_EMAIL_DOMAIN}
  • Resend route TOUS les emails arrivant sur le domaine inbound vers le même webhook - il faut donc parser le champ to pour identifier le workspace
  • Si plusieurs adresses dans to, prendre data.to[0] et chercher celle qui commence par ideas-
  • Exemple : ideas-acme-corp@cool-hedgehog.resend.app → slug = acme-corp

Idempotence - champ emailMessageId :

  • Resend peut rejouer les webhooks en cas d'échec (retry automatique)
  • Le message_id du payload (data.message_id) est unique par email
  • Avant de créer l'idée, vérifier await db.idea.findFirst({ where: { emailMessageId: data.message_id } })
  • Si trouvé → retourner 200 { success: true, ideaId: existing.id } sans recréer

Valeurs par défaut pour soumissions email : | Champ | Valeur | Raison | |-------|--------|--------| | department | "email" | Distingue soumissions email des soumissions formulaire | | estimatedImpact | MODERE | Défaut raisonnable, le Transformateur ajustera | | frequency | PONCTUELLE | Défaut conservateur | | status | SUBMITTED | Statut initial standard |

Récupération du corps email - fallback :

const emailContent = await resend.emails.receiving.get({ emailId: data.email_id });
const bodyText = (
  emailContent.data?.text ??           // texte brut (préféré)
  emailContent.data?.html?.replace(/<[^>]*>/g, ' ').trim() ?? // HTML → texte
  data.subject ??                       // sujet comme fallback
  'Idée soumise par email'              // dernier recours
).trim();

Parsing du champ from :

  • Le champ from peut être au format "Prénom Nom <email@domain.com>" ou "email@domain.com"
  • Extraire l'email avec : from.match(/<([^>]+)>/)?.[1] ?? from.trim()

Structure des fichiers

Fichier Action
src/app/api/webhooks/email/route.ts Créer - handler webhook Resend Inbound
src/lib/email-inbox.ts (ou utils.ts) Modifier - ajouter getWorkspaceInboxEmail()
src/app/(dashboard)/workspace/[workspaceId]/settings/page.tsx Modifier - afficher inbox email
prisma/schema.prisma Modifier - ajouter emailMessageId String? @unique sur Idea
prisma/migrations/YYYYMMDD_add_idea_email_message_id/migration.sql Créer - migration Prisma
.env.example Modifier - ajouter INBOUND_EMAIL_DOMAIN, RESEND_WEBHOOK_SECRET
src/app/api/webhooks/email/route.test.ts Créer - tests Vitest

Conventions architecture à respecter

  • Import PrismaClient : depuis ~/server/db (instance singleton), pas de new PrismaClient() directement dans la route
  • Service email : le SDK Resend est instancié dans src/server/services/email.ts - créer une instance séparée dans la route webhook OU exporter l'instance resend depuis le service email existant
  • Route Handlers : réponses via NextResponse.json() avec les bons codes HTTP
  • Multi-tenant : toujours filtrer par workspaceId lors des requêtes Prisma - ne jamais chercher des idées sans filtre workspace
  • ESM : projet en "type": "module" - pas d'import CommonJS sans .cjs
  • Nommage : fichier route.ts, pas de default export nommé (export POST)

Schéma Prisma - modification requise

Ajouter sur le modèle Idea :

emailMessageId   String?     @unique // idempotence webhook Resend - Story 2.5

Cela permet db.idea.findUnique({ where: { emailMessageId: messageId } }) pour l'idempotence.

Référence story précédente (2.4b) - acquis

  • tsx est en devDependency, script db:seed configuré
  • Import Prisma : import { PrismaClient } from "../generated/prisma" pour les scripts standalone ; dans les routes Next.js, utiliser import { db } from "~/server/db"
  • Pattern Vitest mock : vi.mock("~/server/db", () => ({ db: { idea: { create: mockCreate } } }))
  • services/email.ts utilise le SDK Resend - pattern de mock à réutiliser dans les tests

Apprentissages story précédente (2.4a) - contexte

  • Le modèle LibraryCase est en base, seed exécuté (25 cas disponibles)
  • Le router library.ts avec getAll et getById est fonctionnel
  • Les composants LibraryBrowser, LibraryModal, LibraryCaseCard existent dans src/components/library/
  • Le formulaire IdeaSubmissionForm supporte initialPrefillText, autoOpenLibrary, initialLibraryFilters

Configuration Resend Inbound (steps à faire hors code)

  1. Dans le dashboard Resend : créer un webhook pointant vers https://{app-domain}/api/webhooks/email, sélectionner l'événement email.received
  2. Copier le RESEND_WEBHOOK_SECRET généré → variable d'environnement
  3. Configurer le domaine inbound (ou utiliser le domaine .resend.app fourni par défaut)
  4. Copier le domaine inbound → variable INBOUND_EMAIL_DOMAIN
  5. Aucune configuration DNS custom requise si on utilise le domaine .resend.app

NFR concernés

  • NFR6 : ingestion < 15 min pour 95% des emails - assuré par la réactivité du webhook Resend (< 1 min en pratique)
  • NFR14 : isolation workspace - le slug dans le to garantit le routage correct ; validation workspace en DB avant création
  • NFR7 : disponibilité - Resend stocke les emails même si le webhook est down ; rejeu possible depuis le dashboard

Project Structure Notes

  • Alignement avec la structure définie dans architecture.md : src/app/api/webhooks/email/route.ts est déjà prévu dans l'arborescence cible
  • Le fichier route.ts doit exporter une fonction POST nommée (App Router)
  • src/server/db.ts expose export const db = prisma - utiliser import { db } from "~/server/db"

References

  • [Source: epics.md#Story 2.5 - Soumission d'idée par email (FR15)]
  • [Source: prd.md#FR15, NFR6]
  • [Source: architecture.md#API & Communication Patterns - Route Handlers]
  • [Source: architecture.md#Security Conventions - Webhook email : valider token/secret workspace avant création d'idée]
  • [Source: architecture.md#Project Structure - api/webhooks/email/route.ts]
  • [Source: implementation-artifacts/2-4b-bibliotheque-contenu-seed-au-lancement-fr14-ia6.md - pattern ESM, Prisma import]
  • [Source: src/server/services/email.ts - pattern SDK Resend existant]
  • [Source: src/server/api/routers/idea.ts - pattern matching contributeur par email]
  • [Source: resend.com/docs/dashboard/receiving/introduction - Inbound Email, payload structure, body fetching]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

  • ✅ Task 1 : Utilitaire getWorkspaceInboxEmail dans src/lib/email-inbox.ts, section "Recevoir des idées par email" dans EmailInboxSection (client component) avec bouton Copier + toast
  • ✅ Task 2 : Route POST /api/webhooks/email avec vérification Resend Svix, extraction slug depuis to, idempotence via emailMessageId, appel API Resend pour contenu email, création idée + matching contributeur
  • ✅ Task 3 : Champ emailMessageId sur Idea, migration 20260227120000_add_idea_email_message_id
  • ✅ Task 4 : INBOUND_EMAIL_DOMAIN et RESEND_WEBHOOK_SECRET dans .env.example
  • ✅ Task 5 : 7 tests Vitest (signature invalide, workspace non trouvé, création idée, idempotence, pas d'adresse ideas-, from vide, matching contributeur)

File List

  • aimpact-hub/src/lib/email-inbox.ts (créé)
  • aimpact-hub/src/components/workspace/EmailInboxSection.tsx (créé)
  • aimpact-hub/src/app/(dashboard)/workspace/[workspaceId]/settings/page.tsx (modifié)
  • aimpact-hub/src/app/api/webhooks/email/route.ts (créé)
  • aimpact-hub/src/app/api/webhooks/email/route.test.ts (créé)
  • aimpact-hub/prisma/schema.prisma (modifié)
  • aimpact-hub/prisma/migrations/20260227120000_add_idea_email_message_id/migration.sql (créé)
  • aimpact-hub/.env.example (modifié)