2-7-confirmation-visuelle-et-email-de-soumission-fr16.md 14 KB

Story 2.7 : Confirmation visuelle et email de soumission (FR16)

Status: done

Story

En tant que Contributeur, je veux recevoir une confirmation visuelle immédiate et un email après soumission, afin de savoir que mon idée a bien été enregistrée et pouvoir en soumettre une autre.

Acceptance Criteria

  1. Given je viens de soumettre une idée avec succès When la soumission est validée par le serveur Then la confirmation visuelle s'affiche en moins de 1 seconde (NFR2) And l'écran de confirmation remplace le formulaire (pas de redirection, pas de saut de page) And un message m'indique que je peux suivre le statut de mon idée

  2. Given l'écran de confirmation est affiché When je lis le message Then le message mentionne explicitement qu'un email de confirmation m'a été envoyé And un CTA "Soumettre une autre idée" est disponible pour remettre le formulaire à zéro

  3. Given la soumission est validée When le serveur traite la mutation idea.submit Then un email de confirmation est envoyé à l'adresse contributorEmail de la soumission And l'email contient un CTA "Soumettre une autre idée" avec lien direct vers /submit/[workspaceSlug] And l'email est envoyé en fire-and-forget (ne bloque pas la réponse au contributeur) And en cas d'échec d'envoi email, la soumission reste validée - le contributeur voit la confirmation visuelle

  4. Given le service email (Resend) n'est pas configuré en développement When la soumission est effectuée Then l'email est loggé en console ([email] Submission confirmation (mock): ...) au lieu d'être envoyé And la confirmation visuelle s'affiche normalement

  5. Given le composant SubmissionConfirmation est affiché When je clique sur "Soumettre une autre idée" Then le formulaire est remis à zéro et je peux saisir une nouvelle idée

Tasks / Subtasks

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

    • Subtask 1.1 : Définir et exporter l'interface SendSubmissionConfirmationEmailParams avec : contributorEmail: string, workspaceSlug: string, workspaceName: string
    • Subtask 1.2 : Implémenter la fonction - objet : "Votre idée a bien été transmise - {workspaceName}", corps HTML avec le CTA pointant vers ${baseUrl}/submit/${workspaceSlug}
    • Subtask 1.3 : Respecter le pattern existant : guard if (!resend) → console.log mock avec label [email] Submission confirmation (mock):
    • Subtask 1.4 : Lever throw new Error(...) si Resend retourne une erreur (l'appelant gère via catch)
  • [x] Task 2 : Déclencher l'email depuis la mutation idea.submit dans src/server/api/routers/idea.ts (AC: #3, #4)

    • Subtask 2.1 : Importer sendSubmissionConfirmationEmail depuis ~/server/services/email
    • [x] Subtask 2.2 : Après la transaction (const idea = await ctx.db.$transaction(...)) et après le fire-and-forget LLM enrich, ajouter l'appel email en fire-and-forget :

      void sendSubmissionConfirmationEmail({
      contributorEmail: input.contributorEmail.toLowerCase().trim(),
      workspaceSlug: workspace.slug,
      workspaceName: workspace.name,
      }).catch((err: unknown) => {
      console.error("[email] Submission confirmation failed:", err);
      });
      
    • [x] Subtask 2.3 : S'assurer que workspace.slug et workspace.name sont inclus dans le select de workspace.findUnique (actuellement slug ✓ ; name ✓ dans la sélection existante)

    • [x] Subtask 2.4 : Vérifier que le retour { ideaId: idea.id } est inchangé

  • [x] Task 3 : Mettre à jour SubmissionConfirmation.tsx pour mentionner l'email (AC: #1, #2)

    • Subtask 3.1 : Modifier le texte de confirmation pour indiquer qu'un email a été envoyé :
    • Titre inchangé : "Votre idée a bien été transmise !"
    • Corps actuel : "Elle sera examinée et vous serez tenu(e) informé(e) de son avancement."
    • Ajouter une seconde ligne : "Un email de confirmation vous a été envoyé."
    • Subtask 3.2 : Vérifier que le CTA "Soumettre une autre idée" est présent et fonctionnel (déjà implémenté - vérification seulement)
    • Subtask 3.3 : Conserver role="status", aria-live="polite" et le focus automatique sur le titre (accessibilité WCAG 2.1 AA)
  • [x] Task 4 : Tests (AC: #3, #4)

    • Subtask 4.1 : Créer src/server/services/email.test.ts (ou ajouter à un fichier test existant si présent)
    • Subtask 4.2 : Test : sendSubmissionConfirmationEmail sans RESEND_API_KEY → log console, pas d'erreur levée
    • Subtask 4.3 : Test : sendSubmissionConfirmationEmail avec Resend mocké → resend.emails.send appelé avec les bons params (to, subject, corps contenant le submitUrl)
    • Subtask 4.4 : Test : sendSubmissionConfirmationEmail avec Resend retournant une erreur → throw new Error(...) levée
    • Subtask 4.5 : Vérifier que le test de la mutation idea.submit existant (s'il existe) n'est pas cassé par l'ajout du fire-and-forget email

Dev Notes

Analyse de l'état existant - ce qui est déjà implémenté

SubmissionConfirmation.tsx (Story 2.2) : Le composant de confirmation visuelle est déjà implémenté et fonctionnel :

  • Confirmation verte plein-zone remplaçant le formulaire (pas de navigation)
  • Icône checkmark, titre focusé automatiquement pour accessibilité
  • CTA "Soumettre une autre idée" → onReset() → remet le formulaire à zéro
  • role="status" + aria-live="polite" (WCAG 2.1 AA ✓)
  • Affiché en < 1s via setSubmitted(true) dans le onSuccess de la mutation (NFR2 ✓)

Ce qui manque pour FR16 :

  • La mention "un email de confirmation vous a été envoyé" dans le composant UI
  • La fonction sendSubmissionConfirmationEmail() dans email.ts
  • L'appel fire-and-forget depuis idea.submit

Décision d'implémentation - Email fire-and-forget

Pourquoi fire-and-forget ?

  • Même pattern que l'enrichissement LLM (void fetch(...).catch(...)) - cohérence architecturale
  • L'email ne doit pas bloquer la réponse (NFR2 : confirmation < 1s)
  • En cas d'échec email, la soumission est déjà validée - l'idée est créée en base
  • L'erreur est loguée côté serveur sans impact UX contributeur

Pattern exact à reproduire (depuis idea.ts) :

// Existant (LLM enrich) :
void fetch(`${baseUrl}/api/llm/enrich`, { ... }).catch(() => { /* silencieux */ });

// À ajouter (email confirmation) :
void sendSubmissionConfirmationEmail({
  contributorEmail: input.contributorEmail.toLowerCase().trim(),
  workspaceSlug: workspace.slug,
  workspaceName: workspace.name,
}).catch((err: unknown) => {
  console.error("[email] Submission confirmation failed:", err);
});

Template email de confirmation

const subject = `Votre idée a bien été transmise - ${params.workspaceName}`;
const submitUrl = `${baseUrl}/submit/${params.workspaceSlug}`;
const html = `
  <p>Bonjour,</p>
  <p>Votre idée a bien été transmise à l'équipe de <strong>${escapedName}</strong>. Elle sera examinée et vous serez informé(e) de son avancement.</p>
  <p>Vous souhaitez partager une autre idée ? Cliquez sur le lien ci-dessous :</p>
  <p><a href="${submitUrl}">Soumettre une autre idée →</a></p>
  <p>Merci pour votre contribution.</p>
  <p>- L'équipe ${escapedName}</p>
`;

Escaper workspaceName pour éviter les injections HTML - même pattern que sendInvitationEmail :

const escapedName = params.workspaceName
  .replace(/&/g, "&amp;")
  .replace(/</g, "&lt;")
  .replace(/>/g, "&gt;")
  .replace(/"/g, "&quot;");

Variables d'environnement

Aucune variable d'environnement nouvelle - réutilisation de :

  • RESEND_API_KEY (déjà dans .env.example)
  • EMAIL_FROM (déjà dans .env.example ou fallback "onboarding@resend.dev")
  • NEXT_PUBLIC_APP_URL (déjà utilisé dans idea.ts)

Sélection Prisma - workspace dans idea.submit

La sélection actuelle dans idea.submit est :

select: { id: true, name: true, slug: true }

name et slug sont déjà sélectionnés - aucune modification du select requise.

Structure des fichiers

Fichier Action
aimpact-hub/src/server/services/email.ts Modifier - ajouter sendSubmissionConfirmationEmail + son interface
aimpact-hub/src/server/api/routers/idea.ts Modifier - import + fire-and-forget email dans submit
aimpact-hub/src/components/form/SubmissionConfirmation.tsx Modifier - ajouter ligne "Un email de confirmation vous a été envoyé."
aimpact-hub/src/server/services/email.test.ts Créer - tests Vitest pour la nouvelle fonction

Conventions architecture à respecter

  • Nommage : sendSubmissionConfirmationEmail (camelCase, verbe send + domaine, aligné avec sendInvitationEmail)
  • Interface : SendSubmissionConfirmationEmailParams (PascalCase)
  • Pattern mock dev : guard if (!resend) → console.log("[email] ...") (pattern existant dans email.ts)
  • Erreurs : throw new Error(...) si Resend retourne une erreur - l'appelant gère via .catch()
  • Fire-and-forget : void fn().catch((err: unknown) => { console.error(...) }) - pas de await
  • ESM : imports ES modules uniquement

Apprentissages story précédente (2.6) - contexte pertinent

  • Pattern mock Vitest pour modules externes : vi.mock('resend', () => ({ Resend: vi.fn().mockImplementation(() => ({ emails: { send: vi.fn() } })) }))
  • import { db } from "~/server/db" pour PrismaClient
  • console.error("[email] ...") pour les logs d'erreur (convention préfixe [email])
  • Pattern .catch((err: unknown) => { ... }) pour les fire-and-forget (TypeScript strict)

Dépendances inter-stories

  • Dépend de Story 2.2 : SubmissionConfirmation composant et IdeaSubmissionForm existent et fonctionnent - cette story les étend
  • Dépend de Story 2.1 : sendInvitationEmail pattern dans email.ts - sert de référence directe pour la nouvelle fonction
  • Sans impact sur les stories suivantes (2.8 RGPD, 2.9–2.11) - uniquement côté confirmation

NFR concernés

  • NFR2 : confirmation visuelle en moins de 1 seconde - garanti car l'email est fire-and-forget (ne bloque pas setSubmitted(true))
  • NFR9 : si Resend est indisponible, l'email n'est pas envoyé mais le formulaire reste fonctionnel (l'erreur est attrapée silencieusement côté UX)

Project Structure Notes

  • src/server/services/email.ts est le service email centralisé (architecture.md § Services)
  • src/server/api/routers/idea.ts est le router tRPC existant - modification minimaliste (import + 4 lignes)
  • src/components/form/SubmissionConfirmation.tsx est dans components/form/ (feature-based, aligné architecture)
  • Tests dans src/server/services/email.test.ts co-localisé avec le service (convention *.test.ts)

References

  • [Source: epics.md#Story 2.7 - Confirmation visuelle et email de soumission (FR16)]
  • [Source: epics.md#FR16 - confirmation visuelle + email CTA "Soumettre une autre idée"]
  • [Source: epics.md#NFR2 - confirmation < 1s]
  • [Source: epics.md#NFR9 - formulaire fonctionnel si service LLM/email indisponible]
  • [Source: architecture.md#Services - services/email.ts]
  • [Source: architecture.md#API & Communication Patterns - fire-and-forget pour enrichissement]
  • [Source: implementation-artifacts/2-6-pieces-jointes-a-la-soumission-fr17.md - patterns fire-and-forget, mock Vitest]
  • [Source: implementation-artifacts/2-6-pieces-jointes-a-la-soumission-fr17.md - patterns .catch((err: unknown) => {...})]
  • [Source: src/components/form/SubmissionConfirmation.tsx - composant existant à étendre]
  • [Source: src/server/api/routers/idea.ts - mutation submit, fire-and-forget LLM enrich pattern]
  • [Source: src/server/services/email.ts - sendInvitationEmail pattern de référence]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

  • ✅ Task 1 : sendSubmissionConfirmationEmail + interface SendSubmissionConfirmationEmailParams dans email.ts
  • ✅ Task 2 : Fire-and-forget email dans idea.submit après mutation
  • ✅ Task 3 : SubmissionConfirmation - ajout ligne "Un email de confirmation vous a été envoyé." (avec
    )
  • ✅ Task 4 : 4 tests Vitest (mock sans key, Resend mocké params, throw Resend error) - vi.hoisted mockSend

File List

  • aimpact-hub/src/server/services/email.ts (modifié - sendSubmissionConfirmationEmail + JSDoc header)
  • aimpact-hub/src/server/api/routers/idea.ts (modifié - import + fire-and-forget email)
  • aimpact-hub/src/components/form/SubmissionConfirmation.tsx (modifié - mention email, deux

    séparés)

  • aimpact-hub/src/server/services/email.test.ts (modifié - 3 tests sendSubmissionConfirmationEmail + test XSS escaping)
  • aimpact-hub/src/server/api/routers/idea.submit.test.ts (créé - 3 tests mutation submit fire-and-forget email)
  • Senior Developer Review (AI)

    Date : 2026-02-28 Outcome : Changes Requested → Applied ✅

    Action Items

    • [HIGH] Aucun test intégration pour AC3 "email failure doesn't block submission" - idea.submit.test.ts créé avec 3 tests couvrant le comportement fire-and-forget
    • [MEDIUM] Pas de test XSS/escaping pour sendSubmissionConfirmationEmail - test ajouté dans email.test.ts
    • [MEDIUM] JSDoc header email.ts obsolète (Story 2.1 seulement) - mis à jour avec Story 2.7
    • [MEDIUM] <br /> dans <p> → accessibilité WCAG 2.1 AA - remplacé par deux <p> séparés dans SubmissionConfirmation.tsx