2-1-invitation-de-contributeurs-par-email-fr6-fr7.md 12 KB

Story 2.1: Invitation de contributeurs par email (FR6, FR7)

Status: done

Story

En tant que Transformateur, je veux inviter des contributeurs par email avec un lien vers le formulaire, afin qu'ils puissent soumettre des idées.

Acceptance Criteria

  1. Given j'ai un workspace configuré When je saisis des emails et envoie les invitations Then chaque contributeur reçoit un email avec un lien direct vers le formulaire de soumission (incluant workspaceSlug) And les contributeurs invités sont listés dans le workspace

  2. Given mon workspace est en tier Free When le nombre de contributeurs atteint ou dépasse 5 (FR4) Then l'invitation est bloquée avec un message explicite indiquant la limite du tier Free And un lien vers la mise à niveau est suggéré (optionnel en MVP — simple message suffit)

  3. Given j'invite un email déjà invité pour ce workspace When j'envoie l'invitation Then le système détecte le doublon et affiche un message approprié (pas de double envoi) And l'email existant reste listé avec son statut actuel

  4. Given j'ai envoyé des invitations When je consulte la page contributeurs du workspace Then je vois la liste des contributeurs invités avec leur email et leur statut (invité / a soumis / n'a rien soumis) And le statut "invité" est le défaut pour les contributeurs n'ayant pas encore soumis d'idée

Tasks / Subtasks

  • [x] Task 1 : Modèle de données Contributor (AC: #1, #3, #4)

    • Subtask 1.1 : Créer modèle Contributor dans prisma/schema.prisma : id, workspaceId, email, status (enum: INVITED, SUBMITTED, NOT_SUBMITTED), invitedAt, createdAt
    • Subtask 1.2 : Ajouter relation contributors Contributor[] sur modèle Workspace ; index @@unique([workspaceId, email]) sur Contributor pour éviter doublons
    • Subtask 1.3 : Exécuter prisma migrate dev --name add-contributor-model (db push utilisé)
  • [x] Task 2 : Service email et envoi d'invitations (AC: #1)

    • Subtask 2.1 : Créer src/server/services/email.ts — fonction sendInvitationEmail(contributor, workspace) avec lien {baseUrl}/submit/{workspace.slug}
    • Subtask 2.2 : Configurer provider email (Resend recommandé — resend npm) ; variables RESEND_API_KEY, EMAIL_FROM dans .env.example
    • Subtask 2.3 : Template email : objet clair, corps avec lien direct formulaire, ton neutre (voir PRD Journey 2)
  • [x] Task 3 : Router tRPC contributor (AC: #1, #2, #3, #4)

    • Subtask 3.1 : Créer src/server/api/routers/contributor.ts avec createWorkspaceProcedure
    • Subtask 3.2 : Procédure invite : input { workspaceId, emails: string[] } — valider format email (Zod), vérifier limite tier (5), créer Contributor, envoyer email
    • Subtask 3.3 : Procédure list : retourner contributeurs du workspace avec statut
    • Subtask 3.4 : Enregistrer contributorRouter dans root.ts
  • [x] Task 4 : UI invitation et liste contributeurs (AC: #1, #2, #3, #4)

    • Subtask 4.1 : Créer page src/app/(dashboard)/workspace/[workspaceId]/contributors/page.tsx — formulaire invitation (champ emails, bouton Envoyer) + liste contributeurs
    • Subtask 4.2 : Composant InviteContributorsForm — Input ou Textarea pour saisir emails (séparés par virgule ou ligne), validation côté client, appel contributor.invite
    • Subtask 4.3 : Composant ContributorsList — Table ou liste avec colonnes email, statut (Badge), date invitation
    • Subtask 4.4 : Gérer erreurs : limite tier atteinte, email invalide, doublon — affichage inline (pas de modale)
    • Subtask 4.5 : Lier l'étape onboarding "inviter des contributeurs" à cette page (lien depuis OnboardingChecklist)
  • [x] Task 5 : Tests (AC: #1, #2, #3)

    • Subtask 5.1 : Test unitaire contributor.invite — validation logic (succès, limite, doublon, format email)
    • Subtask 5.2 : Test service email — vérifier contenu (lien workspaceSlug) en mode mock
    • Subtask 5.3 : Test composant InviteContributorsForm — rendu formulaire

Dev Notes

Contexte technique

  • Story 1.6 : src/lib/tier.ts expose FREE_TIER_LIMITS.maxContributors = 5. Utiliser isAtContributorLimit(contributorsCount) ou vérifier contributorsCount >= 5 avant d'accepter une nouvelle invitation.
  • Schéma Prisma actuel : Pas de modèle Contributor. Le modèle Idea n'existe pas encore — le statut "a soumis" sera mis à jour dans Story 2.2 (formulaire soumission). Pour cette story, tous les contributeurs créés ont statut INVITED ou NOT_SUBMITTED (équivalent fonctionnel jusqu'à Story 2.2).
  • Workspace.slug : Déjà existant, unique. URL contributeur : {NEXT_PUBLIC_APP_URL}/submit/{workspace.slug}. Variable NEXT_PUBLIC_APP_URL ou VERCEL_URL pour l'environnement.
  • OnboardingChecklist : L'étape invite_contributors existe. Ajouter un lien vers /workspace/[workspaceId]/contributors pour que le Transformateur puisse accomplir cette étape.

Statuts contributeur (préparation Story 2.9)

Statut Signification
INVITED Invitation envoyée, pas encore de soumission (défaut à la création)
SUBMITTED Au moins une idée soumise (mis à jour en Story 2.2)
NOT_SUBMITTED Relance J+21 envoyée sans soumission (Story 2.10)

Pour Story 2.1 : tous les contributeurs sont INVITED. Story 2.2 mettra à jour en SUBMITTED quand une idée est soumise avec cet email.

Schéma Prisma — modèle Contributor

enum ContributorStatus {
  INVITED
  SUBMITTED
  NOT_SUBMITTED
}

model Contributor {
  id          String            @id @default(cuid())
  workspaceId String
  workspace   Workspace         @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
  email       String
  status      ContributorStatus @default(INVITED)
  invitedAt   DateTime          @default(now())
  createdAt   DateTime          @default(now())

  @@unique([workspaceId, email])
  @@index([workspaceId])
}

// Sur Workspace, ajouter :
//   contributors Contributor[]

Service email — structure

// src/server/services/email.ts
export async function sendInvitationEmail(params: {
  email: string;
  workspaceSlug: string;
  workspaceName: string;
}): Promise<void> {
  const baseUrl = process.env.NEXT_PUBLIC_APP_URL ?? process.env.VERCEL_URL ?? 'http://localhost:3000';
  const submitUrl = `${baseUrl}/submit/${params.workspaceSlug}`;
  // Resend: resend.emails.send({ from, to, subject, html })
}

Architecture Compliance

  • Multi-tenant : Toutes les procédures utilisent createWorkspaceProcedure. Filtrer par workspaceId sur toutes les requêtes Contributor.
  • Pas de données inter-workspace : NFR14 — isolation stricte.
  • Convention stockage : Pas de pièces jointes dans cette story.
  • Prisma : Workspace.slug pour URLs contributeur — déjà en place.

Library / Framework Requirements

  • Resend : npm install resend — API simple, compatible EU. Alternative : SendGrid, Postmark.
  • Zod : Validation emails: z.array(z.string().email()).min(1).max(10) — limiter le nombre d'invitations par batch (éviter spam).
  • shadcn/ui : Input, Button, Badge, Table (ou Card pour liste simple), Toast (confirmation envoi).

File Structure Requirements

Fichier Action
prisma/schema.prisma Modifier — ajouter enum ContributorStatus, modèle Contributor, relation Workspace
prisma/migrations/ Créer via prisma migrate dev
src/server/services/email.ts Créer — sendInvitationEmail
src/server/api/routers/contributor.ts Créer — invite, list
src/server/api/root.ts Modifier — ajouter contributor: contributorRouter
src/app/(dashboard)/workspace/[workspaceId]/contributors/page.tsx Créer
src/components/workspace/InviteContributorsForm.tsx Créer
src/components/workspace/ContributorsList.tsx Créer
.env.example Modifier — ajouter RESEND_API_KEY, EMAIL_FROM, NEXT_PUBLIC_APP_URL

Testing Requirements

  • Unit contributor.invite : succès avec 1 email, blocage à 6e contributeur (tier Free), rejet doublon, validation email invalide
  • Service email : mock Resend, vérifier que le lien contient workspaceSlug
  • Composant : InviteContributorsForm — rendu, validation, appel mutation
  • Framework : Vitest + Testing Library (configuré Story 1.5)

Previous Story Intelligence (Epic 1)

  • createWorkspaceProcedure : Pattern établi dans workspace.ts. Réutiliser pour contributorRouter.
  • tier.ts : FREE_TIER_LIMITS.maxContributors = 5. Ajouter isAtContributorLimit(contributorsCount: number) si absent, ou vérifier contributorsCount >= FREE_TIER_LIMITS.maxContributors avant invite.
  • OnboardingChecklist : Step invite_contributors — ajouter lien vers page contributeurs. Pattern : router.push ou Link vers /workspace/[id]/contributors.
  • Workspace.getTierInfo (Story 1.6) : Retourne contributorsCount. S'assurer que le modèle Contributor est bien compté (relation workspace.contributors).

UX — Formulaire invitation

  • Design tokens : Livinia Chaleureux (fond #fefdfb, primaire #7c3aed)
  • Champ emails : Textarea ou Input avec placeholder "email1@exemple.com, email2@exemple.com" — parser par virgule ou saut de ligne
  • Erreur inline : Sous le champ, pas de modale. Messages : "Limite tier Free atteinte (5 contributeurs)", "Cet email a déjà été invité", "Format email invalide"
  • Confirmation : Toast "X invitation(s) envoyée(s)" après succès

Project Context Reference

  • [Source: epics.md#Story 2.1]
  • [Source: architecture.md#Contributeurs FR6-FR13]
  • [Source: prd.md#FR6, FR7]
  • [Source: prd.md#Tiers Free — 5 contributeurs max]
  • [Source: ux-design-specification.md#J1 Onboarding — step inviter]
  • [Source: 1-6-limites-tier-free-et-affichage-abonnement-fr4-fr5.md#tier.ts]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Senior Developer Review (AI)

Date: 2026-02-27
Outcome: Changes Requested → Fixes applied

Action Items (résolus):

  • [High] N+1 dans contributor.invite — remplacer boucle findUnique par findMany (contributor.ts)
  • [High] XSS email HTML — échapper workspaceName dans le template (email.ts)
  • [Medium] Magic number 5 — utiliser FREE_TIER_LIMITS.maxContributors (InviteContributorsForm.tsx)

Action Items (à faire manuellement):

  • [Medium] Migration Contributor — déjà incluse dans 20260226000000_init_schema (Contributor créé avec Workspace)

Findings non bloquants (LOW):

  • contributor.test.ts teste une fonction de validation custom, pas le router tRPC réel — considérer des tests d'intégration avec mock db

Completion Notes List

  • Modèle Contributor créé avec enum ContributorStatus (INVITED, SUBMITTED, NOT_SUBMITTED)
  • Service email Resend avec fallback log en dev sans API key
  • Router contributor.invite et contributor.list avec createWorkspaceProcedure
  • Page contributeurs avec InviteContributorsForm et ContributorsList
  • OnboardingChecklist : lien "Inviter →" vers page contributeurs
  • Tests : contributor validation, email service (submitUrl), InviteContributorsForm rendu

File List

  • prisma/schema.prisma (modifié)
  • src/server/services/email.ts (créé)
  • src/server/api/routers/contributor.ts (créé)
  • src/server/api/routers/contributor.test.ts (créé)
  • src/server/api/routers/workspace.ts (modifié — getTierInfo contributorsCount)
  • src/server/api/root.ts (modifié — contributorRouter)
  • src/lib/tier.ts (modifié — isAtContributorLimit)
  • src/app/(dashboard)/workspace/[workspaceId]/contributors/page.tsx (créé)
  • src/components/workspace/InviteContributorsForm.tsx (créé)
  • src/components/workspace/InviteContributorsForm.test.tsx (créé)
  • src/components/workspace/ContributorsList.tsx (créé)
  • src/components/workspace/OnboardingChecklist.tsx (modifié — lien invite)
  • src/components/workspace/OnboardingChecklist.test.tsx (modifié)
  • .env.example (modifié)
  • src/server/services/email.test.ts (créé)
  • package.json (modifié — resend)