# 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) - [x] Subtask 1.1 : Ajouter une variable d'environnement `INBOUND_EMAIL_DOMAIN` dans `.env.example` avec une valeur de test (ex. `cool-hedgehog.resend.app`) - [x] 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'}\`` - [x] 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) - [x] 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 : ```typescript 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 : ```typescript 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) - [x] 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 - [x] 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) - [x] Subtask 4.1 : Ajouter `RESEND_WEBHOOK_SECRET` dans `.env.example` (obligatoire en production) - [x] 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) - [x] 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` - [x] Subtask 5.2 : Test : signature invalide → 401 - [x] Subtask 5.3 : Test : workspace non trouvé → 404 - [x] Subtask 5.4 : Test : email valide → idée créée avec les bons champs (contributorEmail, problemDescription, department = "email", estimatedImpact = MODERE, frequency = PONCTUELLE) - [x] Subtask 5.5 : Test : idempotence — deuxième appel avec même `message_id` → 200 sans doublon - [x] 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](https://resend.com/docs/dashboard/receiving/introduction) **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 :** ```typescript 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 "` 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` : ```prisma 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é)