2-10-relance-automatique-j21-fr10.md 22 KB

Story 2.10 : Relance automatique J+21 (FR10)

Status: done

Story

En tant que système, je veux envoyer une relance automatique aux contributeurs sans soumission 21 jours après leur invitation, afin de les inciter à contribuer.

Acceptance Criteria

  1. Given un contributeur a été invité il y a 21 jours ou plus et n'a soumis aucune idée (statut INVITED) When le cron Vercel s'exécute via GET /api/cron/relance Then une relance email est envoyée au contributeur (une seule occurrence, ton neutre, lien direct vers /submit/[workspaceSlug]) And le champ lastRemindedAt du contributeur est mis à jour avec la date d'envoi And le statut du contributeur passe de INVITED à NOT_SUBMITTED

  2. Given un contributeur a déjà reçu une relance (lastRemindedAt non null) When le cron s'exécute à nouveau Then aucune relance n'est envoyée (idempotent - une seule relance automatique par contributeur)

  3. Given un contributeur a soumis une idée (statut SUBMITTED) When le cron s'exécute Then aucune relance n'est envoyée à ce contributeur

  4. Given le Transformateur a désactivé la relance automatique dans les paramètres du workspace (autoRelanceEnabled = false) When le cron s'exécute Then aucune relance n'est envoyée pour les contributeurs de ce workspace

  5. Given le cron endpoint est appelé sans le header Authorization: Bearer CRON_SECRET valide When la requête HTTP arrive sur /api/cron/relance Then une réponse 401 Unauthorized est retournée

  6. Given le cron s'exécute et relance N contributeurs When les relances sont envoyées Then le log de chaque relance est visible dans le workspace (date d'envoi par contributeur via lastRemindedAt) And le endpoint retourne un résumé JSON { sent, failed, total }

Tasks / Subtasks

  • [x] Task 1 : Migration Prisma - champs relance (AC: #1, #4, #6)

    • 1.1 : Ajouter lastRemindedAt DateTime? au modèle Contributor
    • 1.2 : Ajouter autoRelanceEnabled Boolean @default(true) au modèle Workspace
    • 1.3 : Générer et appliquer la migration : npx prisma migrate dev --name add_relance_fields
  • [x] Task 2 : Service email - sendRelanceEmail() (AC: #1)

    • 2.1 : Ajouter la fonction sendRelanceEmail dans src/server/services/email.ts (même pattern que sendInvitationEmail)
    • 2.2 : Ton neutre, lien direct formulaire, pas d'urgence - voir Dev Notes pour le contenu exact
  • [x] Task 3 : Route handler cron - src/app/api/cron/relance/route.ts (AC: #1, #2, #3, #4, #5, #6)

    • 3.1 : Créer le fichier src/app/api/cron/relance/route.ts avec handler GET
    • 3.2 : Vérifier CRON_SECRET via header Authorization: Bearer ...
    • 3.3 : Requête Prisma : contributeurs éligibles (status = INVITED, invitedAt <= J-21, lastRemindedAt IS NULL, workspace.autoRelanceEnabled = true)
    • 3.4 : Boucle d'envoi avec try/catch individuel + mise à jour lastRemindedAt et status = NOT_SUBMITTED
    • 3.5 : Retourner résumé JSON { sent, failed, total }
  • [x] Task 4 : Configuration Vercel Cron (AC: #1)

    • 4.1 : Créer vercel.json à la racine du projet aimpact-hub/ avec schedule quotidien
    • 4.2 : Ajouter CRON_SECRET dans src/env.js (optionnel, Zod)
    • 4.3 : Ajouter CRON_SECRET dans .env.example
  • [x] Task 5 : Toggle workspace - désactivation relance automatique (AC: #4)

    • 5.1 : Étendre workspaceUpdateInputSchema dans workspace.schema.ts : ajouter autoRelanceEnabled: z.boolean().optional()
    • 5.2 : Étendre workspace.update dans workspace.ts pour persister autoRelanceEnabled
    • 5.3 : Ajouter un composant toggle dans la page Settings du workspace
  • [x] Task 6 : Tests (AC: #1, #2, #3, #4, #5)

    • 6.1 : Tests unitaires sendRelanceEmail dans email.test.ts (même pattern que tests existants)
    • 6.2 : Tests unitaires pour la logique cron (éligibilité, idempotence, workspace désactivé, sécurité CRON_SECRET)

Dev Notes

Analyse de l'état existant - ce qui est DÉJÀ implémenté (NE PAS refaire)

email.ts - service email existant (Stories 2.1, 2.7) :

  • Provider : Resend (import { Resend } from "resend")
  • Helper getResend() : retourne null si RESEND_API_KEY absent → log console en dev
  • Helper getBaseUrl() : NEXT_PUBLIC_APP_URL > VERCEL_URL > localhost:3000
  • Fonctions existantes : sendInvitationEmail(), sendSubmissionConfirmationEmail()
  • Pattern HTML escaping anti-XSS sur workspaceName
  • Variable EMAIL_FROM : process.env.EMAIL_FROM ?? "onboarding@resend.dev"

contributor.ts (router) - déjà fonctionnel :

  • invite : crée le contributeur, envoie l'email, vérifie limites tier
  • list : db.contributor.findMany({ where: { workspaceId }, orderBy: { invitedAt: "desc" } })
  • Utilise createWorkspaceProcedure pour l'auth workspace

idea.ts (router, ligne ~74) - transition INVITED → SUBMITTED déjà implémentée :

if (contributor && contributor.status === "INVITED") {
  await tx.contributor.update({
    where: { id: contributor.id },
    data: { status: "SUBMITTED" },
  });
}

Aucune modification à idea.ts pour cette story.

Schéma Prisma actuel - Contributor :

  • id, workspaceId, email, status (enum INVITED/SUBMITTED/NOT_SUBMITTED), invitedAt, createdAt, ideas[]
  • Contrainte unique : @@unique([workspaceId, email])
  • Manque : lastRemindedAt (à ajouter)

Schéma Prisma actuel - Workspace :

  • id, name, slug, sector, companySize, contactEmail, tier, llmCallsThisMonth, llmCallsResetAt, ownerId, contributors[], ideas[]
  • Manque : autoRelanceEnabled (à ajouter)

Page Settings (settings/page.tsx) - existe :

  • Affiche WorkspaceSettingsForm (secteur, taille), SubscriptionStatus, EmailInboxSection
  • Le toggle relance doit être ajouté ici

workspace.schema.ts - schéma update actuel :

  • Valide workspaceId, sector (optional), companySize (optional)
  • Étendre pour inclure autoRelanceEnabled

env.js - validation variables d'environnement :

  • Utilise @t3-oss/env-nextjs avec Zod
  • Pattern : variables optionnelles avec z.string().optional()
  • Ajouter CRON_SECRET

Modifications précises - Task 1 : Migration Prisma

Modèle Contributor - ajouter :

model Contributor {
    // ... champs existants ...
    lastRemindedAt DateTime?   // Story 2.10 : date de la relance J+21 (null = jamais relancé)
    // ... reste identique ...
}

Modèle Workspace - ajouter :

model Workspace {
    // ... champs existants ...
    autoRelanceEnabled Boolean @default(true) // Story 2.10 : désactivable par le Transformateur
    // ... reste identique ...
}

Commande migration :

cd aimpact-hub
npx prisma migrate dev --name add_relance_fields

Modifications précises - Task 2 : sendRelanceEmail()

Ajouter dans src/server/services/email.ts - MÊME pattern que sendInvitationEmail :

export interface SendRelanceEmailParams {
  email: string;
  workspaceSlug: string;
  workspaceName: string;
}

export async function sendRelanceEmail(
  params: SendRelanceEmailParams
): Promise<void> {
  const baseUrl = getBaseUrl();
  const submitUrl = `${baseUrl}/submit/${params.workspaceSlug}`;
  const from = process.env.EMAIL_FROM ?? "onboarding@resend.dev";

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

  const subject = `Rappel : partagez vos idées - ${params.workspaceName}`;
  const html = `
    <p>Bonjour,</p>
    <p>Il y a quelques semaines, vous avez été invité(e) à partager vos idées pour la transformation de <strong>${escapedName}</strong>.</p>
    <p>Votre expérience terrain est précieuse. Si vous avez un problème récurrent ou une opportunité d'amélioration, n'hésitez pas à le partager :</p>
    <p><a href="${submitUrl}">Soumettre une idée →</a></p>
    <p>2 minutes suffisent pour décrire un problème ou une opportunité.</p>
    <p>- L'équipe ${escapedName}</p>
  `;

  const resend = getResend();
  if (!resend) {
    console.log("[email] Relance (mock):", {
      to: params.email,
      subject,
      submitUrl,
    });
    return;
  }

  const { error } = await resend.emails.send({ from, to: params.email, subject, html });
  if (error) {
    throw new Error(`Échec envoi relance: ${error.message}`);
  }
}

Ton de l'email : neutre, non-intrusif, valorisant la contribution (UX spec J2b : « jamais de harcèlement »).

Modifications précises - Task 3 : Route handler cron

Créer src/app/api/cron/relance/route.ts :

import { type NextRequest, NextResponse } from "next/server";
import { db } from "~/server/db";
import { sendRelanceEmail } from "~/server/services/email";

export async function GET(req: NextRequest) {
  const authHeader = req.headers.get("authorization");
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const twentyOneDaysAgo = new Date();
  twentyOneDaysAgo.setDate(twentyOneDaysAgo.getDate() - 21);

  const contributors = await db.contributor.findMany({
    where: {
      status: "INVITED",
      invitedAt: { lte: twentyOneDaysAgo },
      lastRemindedAt: null,
      workspace: { autoRelanceEnabled: true },
    },
    include: {
      workspace: { select: { slug: true, name: true } },
    },
  });

  let sent = 0;
  let failed = 0;

  for (const contributor of contributors) {
    try {
      await sendRelanceEmail({
        email: contributor.email,
        workspaceSlug: contributor.workspace.slug,
        workspaceName: contributor.workspace.name,
      });

      await db.contributor.update({
        where: { id: contributor.id },
        data: {
          lastRemindedAt: new Date(),
          status: "NOT_SUBMITTED",
        },
      });

      sent++;
    } catch (error) {
      console.error(`[cron/relance] Échec pour ${contributor.email}:`, error);
      failed++;
    }
  }

  return NextResponse.json({ sent, failed, total: contributors.length });
}

Points critiques :

  • Le try/catch individuel évite qu'un échec d'envoi bloque les autres
  • lastRemindedAt ET status = NOT_SUBMITTED sont mis à jour ensemble après envoi réussi
  • La requête Prisma filtre par workspace.autoRelanceEnabled pour respecter AC #4
  • lastRemindedAt: null garantit l'idempotence (AC #2)

Modifications précises - Task 4 : Configuration Vercel Cron

Créer aimpact-hub/vercel.json :

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "crons": [
    {
      "path": "/api/cron/relance",
      "schedule": "0 9 * * *"
    }
  ]
}
  • Schedule : tous les jours à 9h UTC (11h Paris été, 10h hiver)
  • Vercel envoie automatiquement CRON_SECRET dans le header Authorization: Bearer ...
  • Les cron jobs ne s'exécutent qu'en production (pas en preview)
  • Plan Hobby : max 2 cron jobs, durée max 60s

Ajouter dans src/env.js section server :

CRON_SECRET: z.string().optional(),

Ajouter dans runtimeEnv :

CRON_SECRET: process.env.CRON_SECRET,

Ajouter dans .env.example :

# Story 2.10 : Cron relance J+21 (Vercel Cron)
# Générer avec : openssl rand -hex 32
# Configuré automatiquement par Vercel en production
CRON_SECRET=""

Modifications précises - Task 5 : Toggle workspace

workspace.schema.ts - étendre :

export const workspaceUpdateInputSchema = z.object({
  workspaceId: z.string().cuid(),
  sector: sectorSchema.optional().nullable(),
  companySize: z.number().int().positive().max(10000).optional().nullable(),
  autoRelanceEnabled: z.boolean().optional(), // Story 2.10
});

workspace.ts router - étendre update : Ajouter dans l'objet data du db.workspace.update :

...(input.autoRelanceEnabled !== undefined && {
  autoRelanceEnabled: input.autoRelanceEnabled,
}),

Composant toggle - à ajouter dans la page Settings : Créer un composant AutoRelanceToggle (ou l'intégrer dans WorkspaceSettingsForm) :

  • Utiliser shadcn Switch + Label
  • Appel tRPC workspace.update avec { workspaceId, autoRelanceEnabled }
  • État initial depuis les données workspace (ajouter autoRelanceEnabled au fetch dans settings/page.tsx)
  • Label : "Relance automatique J+21" + description : "Envoyer automatiquement un rappel aux contributeurs qui n'ont pas soumis d'idée 21 jours après leur invitation"
  • Toast de confirmation après toggle

Structure des fichiers

Fichier Action
aimpact-hub/prisma/schema.prisma Modifier - ajouter lastRemindedAt sur Contributor, autoRelanceEnabled sur Workspace
aimpact-hub/prisma/migrations/YYYYMMDDHHMMSS_add_relance_fields/migration.sql Créer - migration auto-générée
aimpact-hub/src/server/services/email.ts Modifier - ajouter sendRelanceEmail()
aimpact-hub/src/app/api/cron/relance/route.ts Créer - handler cron GET
aimpact-hub/vercel.json Créer - config cron Vercel
aimpact-hub/src/env.js Modifier - ajouter CRON_SECRET
aimpact-hub/.env.example Modifier - ajouter CRON_SECRET
aimpact-hub/src/server/api/routers/workspace.schema.ts Modifier - ajouter autoRelanceEnabled
aimpact-hub/src/server/api/routers/workspace.ts Modifier - étendre update
aimpact-hub/src/app/(dashboard)/workspace/[workspaceId]/settings/page.tsx Modifier - passer autoRelanceEnabled au composant
aimpact-hub/src/components/workspace/AutoRelanceToggle.tsx Créer - toggle switch
aimpact-hub/src/server/services/email.test.ts Modifier - ajouter tests sendRelanceEmail
aimpact-hub/src/app/api/cron/relance/route.test.ts Créer - tests handler cron

Comportement du statut NOT_SUBMITTED

  • Transition : INVITED → NOT_SUBMITTED se fait UNIQUEMENT lors de l'envoi de la relance J+21 (cette story)
  • Affichage : Déjà géré par Story 2.9 (ContributorsList.tsx affiche un badge ambre)
  • Impact Story 2.11 : La relance manuelle (Story 2.11) ciblera tous les contributeurs (INVITED + NOT_SUBMITTED) - cette story ne doit pas bloquer ce cas
  • Un contributeur NOT_SUBMITTED qui soumet une idée passera à SUBMITTED (déjà géré par idea.submit dans idea.ts - vérifier que la condition couvre aussi NOT_SUBMITTED, pas seulement INVITED)

ATTENTION - Vérification critique dans idea.ts : La condition existante est if (contributor && contributor.status === "INVITED"). Elle ne couvre PAS NOT_SUBMITTED. Il faut étendre cette condition :

if (contributor && (contributor.status === "INVITED" || contributor.status === "NOT_SUBMITTED")) {
  await tx.contributor.update({
    where: { id: contributor.id },
    data: { status: "SUBMITTED" },
  });
}

Ajouter cette modification dans Task 3 ou comme sous-tâche dédiée.

Conventions architecture à respecter

  • Route Handler : fichier dans src/app/api/cron/relance/route.ts - aligné avec l'arborescence architecture
  • Nommage : sendRelanceEmail (camelCase), autoRelanceEnabled (camelCase Prisma)
  • Multi-tenant : la requête Prisma filtre via workspace.autoRelanceEnabled - pas besoin de workspaceId explicite car on itère sur tous les workspaces
  • Erreurs : log serveur (console.error) - jamais d'erreur brute exposée
  • Sécurité : CRON_SECRET vérifié en premier (fail-fast)
  • Tests : Vitest, mock Resend, mock Prisma
  • Pas de Skeleton/UI sur le cron - c'est un job backend

Contraintes Vercel Cron

  • Plan Hobby : max 2 cron jobs, durée max 60 secondes
  • Le handler doit être rapide - en cas de nombreux contributeurs éligibles (ex. 100+), considérer un batch limit
  • Les cron jobs ne s'exécutent qu'en production (pas en preview ni en dev local)
  • Pour tester en local : appeler directement GET /api/cron/relance avec un header Authorization: Bearer <test-secret>

Variables d'environnement

Variable Requise Description
CRON_SECRET Optionnel (obligatoire en prod) Secret pour sécuriser le cron endpoint. Généré avec openssl rand -hex 32. Configuré automatiquement par Vercel.

Aucune autre nouvelle variable requise - RESEND_API_KEY et EMAIL_FROM sont déjà configurés.

Dépendances inter-stories

  • Dépend de Story 2.1 : modèle Contributor, sendInvitationEmail (pattern email), contributorRouter
  • Dépend de Story 2.7 : sendSubmissionConfirmationEmail (pattern à suivre)
  • Dépend de Story 2.9 : affichage du statut NOT_SUBMITTED dans ContributorsList.tsx (badge ambre)
  • Précède Story 2.11 : La relance manuelle (Story 2.11) ajoutera sendManualRelanceEmail et un bouton CDO - la relance auto ne bloque pas
  • Impact sur idea.ts : étendre la condition INVITED → inclure NOT_SUBMITTED pour la transition vers SUBMITTED
  • Sans impact sur les stories 3.x et 4.x

NFR concernés

  • NFR7 : Disponibilité 99% - le cron ne doit pas crasher si un email échoue (try/catch individuel)
  • NFR8 : Pas d'appel LLM dans cette story - pas concerné
  • NFR9 : Pas d'impact sur le flux contributeur - la relance est un email asynchrone
  • NFR13 : Hébergement EU - Resend et Vercel Cron sont configurés EU
  • NFR14 : Isolation workspace - la requête Prisma filtre par workspace via workspace.autoRelanceEnabled

Apprentissages des stories précédentes

  • Story 2.1 : Pattern sendInvitationEmail - COPIER exactement ce pattern pour sendRelanceEmail (même structure, même escaping HTML, même fallback mock en dev)
  • Story 2.7 : Pattern sendSubmissionConfirmationEmail - même structure, CTA avec lien direct formulaire
  • Story 2.9 : Le badge ambre NOT_SUBMITTED est déjà géré dans ContributorsList.tsx - pas de modification nécessaire côté affichage
  • Story 1.4 : Pattern workspace.update pour persister les champs - étendre pour autoRelanceEnabled
  • Tests : Mock Resend avec vi.mock("resend", ...) - pattern dans email.test.ts
  • Pattern env.js : Variables optionnelles avec z.string().optional() - suivre pour CRON_SECRET

UX - Flux relance (spec J2b)

  • Une seule relance automatique - jamais de harcèlement
  • Ton neutre, non-intrusif - valoriser la contribution, pas créer de culpabilité
  • Lien direct vers le formulaire - /submit/[workspaceSlug]
  • Log visible côté CDO - lastRemindedAt affiché dans la liste contributeurs (déjà géré par la colonne date dans ContributorsList.tsx - ajouter l'info "Relancé le..." si pertinent)

Références sources

  • [Source: epics.md#Story 2.10 - Relance automatique J+21 (FR10)]
  • [Source: prd.md#FR10 - relance auto 21 jours]
  • [Source: architecture.md#Route Handlers - api/cron/relance]
  • [Source: architecture.md#Services - services/email.ts]
  • [Source: ux-design-specification.md#J2b - Relance contributeur silencieux]
  • [Source: schema.prisma#ContributorStatus - enum INVITED / SUBMITTED / NOT_SUBMITTED]
  • [Source: src/server/services/email.ts - pattern sendInvitationEmail (Resend)]
  • [Source: src/server/api/routers/contributor.ts - router existant]
  • [Source: src/server/api/routers/workspace.ts - router update]
  • [Source: src/server/api/routers/workspace.schema.ts - schéma update]
  • [Source: src/app/(dashboard)/workspace/[workspaceId]/settings/page.tsx - page settings]
  • [Source: src/env.js - validation variables d'environnement]
  • [Source: implementation-artifacts/2-9-liste-des-contributeurs-et-statut-fr9.md - patterns tests, badges]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

  • Migration Prisma : lastRemindedAt (Contributor), autoRelanceEnabled (Workspace) - db push appliqué
  • Service sendRelanceEmail : pattern Resend identique à sendInvitationEmail, ton neutre
  • Route cron /api/cron/relance : GET, CRON_SECRET Bearer, filtre J-21 + INVITED + lastRemindedAt null + autoRelanceEnabled
  • Transition INVITED/NOT_SUBMITTED → SUBMITTED étendue dans idea.ts et webhook email
  • Toggle AutoRelanceToggle dans page Settings avec shadcn Switch
  • Tests : 3 pour sendRelanceEmail, 5 pour cron route, 1 pour idea.test (NOT_SUBMITTED)
  • Colonne "Relancé le" dans ContributorsList.tsx pour afficher lastRemindedAt (AC #6)
  • Scope anticipé Story 2.11 : ManualRelanceLog (schema.prisma) et procédures sendManualRelance/relanceLogs (contributor.ts) implémentés en avance pour réduire la friction sprint suivant

File List

  • aimpact-hub/prisma/schema.prisma (modifié - lastRemindedAt + autoRelanceEnabled + ManualRelanceLog pré-implémenté pour Story 2.11)
  • aimpact-hub/prisma/migrations/20260228100000_add_relance_fields/migration.sql (créé)
  • aimpact-hub/src/server/services/email.ts (modifié)
  • aimpact-hub/src/app/api/cron/relance/route.ts (créé)
  • aimpact-hub/src/app/api/cron/relance/route.test.ts (créé)
  • aimpact-hub/vercel.json (créé)
  • aimpact-hub/src/env.js (modifié)
  • aimpact-hub/.env.example (modifié)
  • aimpact-hub/src/server/api/routers/workspace.schema.ts (modifié)
  • aimpact-hub/src/server/api/routers/workspace.ts (modifié)
  • aimpact-hub/src/app/(dashboard)/workspace/[workspaceId]/settings/page.tsx (modifié)
  • aimpact-hub/src/components/workspace/AutoRelanceToggle.tsx (créé)
  • aimpact-hub/src/components/ui/switch.tsx (ajouté via shadcn)
  • aimpact-hub/src/server/services/email.test.ts (modifié)
  • aimpact-hub/src/server/api/routers/idea.ts (modifié - NOT_SUBMITTED)
  • aimpact-hub/src/app/api/webhooks/email/route.ts (modifié - NOT_SUBMITTED)
  • aimpact-hub/src/server/api/routers/idea.test.ts (modifié)
  • aimpact-hub/src/components/workspace/ContributorsList.tsx (modifié - colonne lastRemindedAt AC #6)
  • aimpact-hub/src/server/api/routers/contributor.ts (modifié - sendManualRelance + relanceLogs pré-implémentés pour Story 2.11 [scope anticipé])