# 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) - [x] 1.1 : Ajouter `lastRemindedAt DateTime?` au modèle `Contributor` - [x] 1.2 : Ajouter `autoRelanceEnabled Boolean @default(true)` au modèle `Workspace` - [x] 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) - [x] 2.1 : Ajouter la fonction `sendRelanceEmail` dans `src/server/services/email.ts` (même pattern que `sendInvitationEmail`) - [x] 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) - [x] 3.1 : Créer le fichier `src/app/api/cron/relance/route.ts` avec handler `GET` - [x] 3.2 : Vérifier `CRON_SECRET` via header `Authorization: Bearer ...` - [x] 3.3 : Requête Prisma : contributeurs éligibles (`status = INVITED`, `invitedAt <= J-21`, `lastRemindedAt IS NULL`, `workspace.autoRelanceEnabled = true`) - [x] 3.4 : Boucle d'envoi avec try/catch individuel + mise à jour `lastRemindedAt` et `status = NOT_SUBMITTED` - [x] 3.5 : Retourner résumé JSON `{ sent, failed, total }` - [x] Task 4 : Configuration Vercel Cron (AC: #1) - [x] 4.1 : Créer `vercel.json` à la racine du projet `aimpact-hub/` avec schedule quotidien - [x] 4.2 : Ajouter `CRON_SECRET` dans `src/env.js` (optionnel, Zod) - [x] 4.3 : Ajouter `CRON_SECRET` dans `.env.example` - [x] Task 5 : Toggle workspace - désactivation relance automatique (AC: #4) - [x] 5.1 : Étendre `workspaceUpdateInputSchema` dans `workspace.schema.ts` : ajouter `autoRelanceEnabled: z.boolean().optional()` - [x] 5.2 : Étendre `workspace.update` dans `workspace.ts` pour persister `autoRelanceEnabled` - [x] 5.3 : Ajouter un composant toggle dans la page Settings du workspace - [x] Task 6 : Tests (AC: #1, #2, #3, #4, #5) - [x] 6.1 : Tests unitaires `sendRelanceEmail` dans `email.test.ts` (même pattern que tests existants) - [x] 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 :** ```typescript 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 :** ```prisma model Contributor { // ... champs existants ... lastRemindedAt DateTime? // Story 2.10 : date de la relance J+21 (null = jamais relancé) // ... reste identique ... } ``` **Modèle Workspace - ajouter :** ```prisma model Workspace { // ... champs existants ... autoRelanceEnabled Boolean @default(true) // Story 2.10 : désactivable par le Transformateur // ... reste identique ... } ``` **Commande migration :** ```bash 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` : ```typescript export interface SendRelanceEmailParams { email: string; workspaceSlug: string; workspaceName: string; } export async function sendRelanceEmail( params: SendRelanceEmailParams ): Promise { const baseUrl = getBaseUrl(); const submitUrl = `${baseUrl}/submit/${params.workspaceSlug}`; const from = process.env.EMAIL_FROM ?? "onboarding@resend.dev"; const escapedName = params.workspaceName .replace(/&/g, "&") .replace(//g, ">") .replace(/"/g, """); const subject = `Rappel : partagez vos idées - ${params.workspaceName}`; const html = `

Bonjour,

Il y a quelques semaines, vous avez été invité(e) à partager vos idées pour la transformation de ${escapedName}.

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 :

Soumettre une idée →

2 minutes suffisent pour décrire un problème ou une opportunité.

- L'équipe ${escapedName}

`; 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` : ```typescript 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` :** ```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` :** ```typescript CRON_SECRET: z.string().optional(), ``` **Ajouter dans `runtimeEnv` :** ```typescript 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 :** ```typescript 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` : ```typescript ...(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 : ```typescript 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 ` ### 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é])