Status: done
En tant que système, je veux enrichir automatiquement chaque idée soumise via LLM (titre, domaine, type IA, explication, scores), afin que le CDO découvre une fiche déjà structurée et qualifiée.
Given une idée vient d'être créée (via formulaire web ou email)
When le système déclenche l'enrichissement asynchrone post-soumission
Then la Route Handler POST /api/llm/enrich est appelée avec { ideaId, workspaceId }
And l'idée est mise à jour en base avec : llmTitle (< 8 mots), llmDomain, llmAiType, llmExplanation (2-3 phrases), llmScoreImpact (1-5), llmScoreFeasibility (1-5), llmScoreUrgency (1-5), llmEnrichedAt
And l'enrichissement s'effectue en moins de 10 secondes pour 90% des cas (NFR4)
Given l'appel LLM échoue (timeout 8s côté service, erreur API) ou dépasse 30 secondes
When le fallback est activé
Then l'idée est marquée llmEnrichFailed = true en base
And aucune donnée LLM partielle n'est écrite (atomicité)
And la fiche affiche l'indicateur "À qualifier manuellement" dans l'interface CDO (implémentation UI en Story 3.4)
Given l'idée est marquée llmEnrichFailed = true
When le CDO clique sur "Relancer l'enrichissement" depuis la fiche (UI Story 3.4)
Then la procédure tRPC idea.retryEnrich est appelée
And la procédure vérifie que llmEnrichFailed === true avant de relancer
And en cas de succès, llmEnrichFailed repasse à false et les champs LLM sont remplis
Given le workspace est en tier Free et a atteint 30 idées enrichies (NFR11)
When une nouvelle soumission est créée
Then l'enrichissement LLM est ignoré silencieusement (aucune erreur côté contributeur)
And llmEnrichFailed = true n'est PAS écrit (l'idée est simplement créée sans enrichissement)
And le compteur llmCallsThisMonth n'est pas incrémenté
Given le workspace dépasse 50 appels LLM/mois en tier Free (NFR12)
When un enrichissement est demandé
Then la route retourne { skipped: true, reason: "llm_limit_reached" } sans appeler OpenAI
Given la Route Handler POST /api/llm/enrich est appelée
When le handler traite la requête
Then il vérifie que l'idée appartient bien au workspaceId fourni avant enrichissement (anti-IDOR, NFR14)
And si l'idée n'appartient pas au workspace → 401 Unauthorized, aucun enrichissement
Given l'enrichissement LLM réussit
When le compteur est mis à jour
Then workspace.llmCallsThisMonth est incrémenté de 1 (identique au pattern de Story 2.3)
[x] Task 1 : Fonction enrichIdea dans services/llm.ts (AC: #1, #2)
[x] Subtask 1.1 : Ajouter l'interface EnrichIdeaParams et EnrichIdeaResult dans src/server/services/llm.ts
export interface EnrichIdeaParams {
ideaId: string;
workspaceId: string;
problemDescription: string;
department: string;
sector?: string | null;
companySize?: number | null;
}
export interface EnrichIdeaResult {
llmTitle: string;
llmDomain: string;
llmAiType: string;
llmExplanation: string;
llmScoreImpact: number;
llmScoreFeasibility: number;
llmScoreUrgency: number;
}
[x] Subtask 1.2 : Implémenter enrichIdea(params: EnrichIdeaParams): Promise<EnrichIdeaResult | null> avec :
AbortController timeout 8000ms (8s pour laisser 2s de marge réseau vs NFR4 10s)
Modèle gpt-4o-mini avec response_format: { type: "json_object" }
Prompt système en français, sans jargon technique (conforme FR18b)
Parse du JSON retourné avec validation Zod
Retourne null en cas d'erreur (le handler met à jour llmEnrichFailed)
[x] Subtask 1.3 : Prompt système à utiliser :
Tu enrichis une idée soumise par un collaborateur en entreprise.
Tu réponds UNIQUEMENT en JSON valide. Tu écris UNIQUEMENT en français.
Tu ne dois JAMAIS utiliser : NLP, OCR, ML, LLM, API, IA, algorithme, modèle dans l'explication.
Décris ce que la technologie ferait concrètement, en langage métier accessible.
[x] Subtask 1.4 : Prompt utilisateur à construire dynamiquement :
Idée soumise : {problemDescription}
Département : {department}
Secteur : {sectorLabel} — Taille : {sizeHint}
Réponds en JSON avec exactement ces champs :
{
"llmTitle": "titre court en français (5 mots maximum, sans ponctuation finale)",
"llmDomain": "domaine métier en 1-3 mots (ex: Supply Chain, Finance, RH)",
"llmAiType": "type de solution en langage métier (ex: Automatisation, Analyse de données, Aide à la décision)",
"llmExplanation": "2 à 3 phrases expliquant ce que la solution ferait concrètement pour ce problème",
"llmScoreImpact": entier entre 1 et 5,
"llmScoreFeasibility": entier entre 1 et 5,
"llmScoreUrgency": entier entre 1 et 5
}
[x] Subtask 1.5 : Schema Zod pour valider la réponse LLM (protège contre les hallucinations) :
const enrichResultSchema = z.object({
llmTitle: z.string().min(1).max(60),
llmDomain: z.string().min(1).max(50),
llmAiType: z.string().min(1).max(80),
llmExplanation: z.string().min(10).max(600),
llmScoreImpact: z.number().int().min(1).max(5),
llmScoreFeasibility: z.number().int().min(1).max(5),
llmScoreUrgency: z.number().int().min(1).max(5),
});
[x] Task 2 : Route Handler POST /api/llm/enrich (AC: #1, #2, #4, #5, #6, #7)
src/app/api/llm/enrich/route.ts — route POST Next.js App Router{ ideaId: z.string().cuid(), workspaceId: z.string().cuid() }[x] Subtask 2.3 : Charger l'idée et valider l'appartenance au workspace (anti-IDOR) :
const idea = await db.idea.findUnique({
where: { id: ideaId },
select: { id: true, workspaceId: true, problemDescription: true, department: true },
});
if (!idea || idea.workspaceId !== workspaceId) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
[x] Subtask 2.4 : Charger le workspace et vérifier les limites tier (NFR11, NFR12) :
Compter les idées enrichies du workspace : db.idea.count({ where: { workspaceId, llmEnrichFailed: false, llmEnrichedAt: { not: null } } })
Si count >= 30 (FREE_TIER_LIMITS.maxIdeasWithLlm) ET tier === FREE → return { skipped: true, reason: "idea_limit_reached" }
Si !isLlmAllowed(workspace) → return { skipped: true, reason: "llm_limit_reached" }
[x] Subtask 2.5 : Appeler enrichIdea(params) avec timeout global de 30s via AbortController externe (fallback NFR4)
[x] Subtask 2.6 : Si enrichIdea retourne null (erreur/timeout) :
await db.idea.update({
where: { id: ideaId },
data: { llmEnrichFailed: true },
});
return NextResponse.json({ success: false, enriched: false });
[x] Subtask 2.7 : Si succès, mettre à jour l'idée ET incrémenter le compteur en transaction :
await db.$transaction([
db.idea.update({
where: { id: ideaId },
data: { ...result, llmEnrichedAt: new Date(), llmEnrichFailed: false },
}),
db.workspace.update({
where: { id: workspaceId },
data: { llmCallsThisMonth: { increment: 1 } },
}),
]);
return NextResponse.json({ success: true, enriched: true });
[x] Task 3 : Déclenchement asynchrone post-soumission formulaire (AC: #1)
[x] Subtask 3.1 : Dans src/server/api/routers/idea.ts, après la transaction idea.create, ajouter un fire-and-forget :
// Fire-and-forget — pas d'await, ne bloque pas la réponse au contributeur
void fetch(`${process.env.NEXT_PUBLIC_APP_URL}/api/llm/enrich`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ideaId: idea.id, workspaceId: workspace.id }),
}).catch(() => { /* silencieux — le fallback llmEnrichFailed sera positionné par la route */ });
[x] Subtask 3.2 : Ajouter NEXT_PUBLIC_APP_URL dans src/env.js côté server (déjà dans .env.example) pour l'URL interne
[x] Task 4 : Déclenchement asynchrone post-soumission email (AC: #1)
src/app/api/webhooks/email/route.ts, après la transaction de création d'idée, ajouter le même fire-and-forget (identique à Subtask 3.1) avec ideaId et workspace.id[x] Subtask 4.2 : Utiliser after() de next/server (Next.js 15 stable) plutôt que fire-and-forget brut si disponible dans ce contexte :
import { after } from 'next/server';
// après la création de l'idée :
after(async () => {
await fetch(`${process.env.NEXT_PUBLIC_APP_URL}/api/llm/enrich`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ideaId: idea.id, workspaceId: workspace.id }),
});
});
[x] Task 5 : Procédure tRPC idea.retryEnrich pour relance manuelle (AC: #3)
[x] Subtask 5.1 : Ajouter dans src/server/api/routers/idea.ts (via createWorkspaceProcedure ou protectedProcedure) :
retryEnrich: protectedProcedure
.input(z.object({ ideaId: z.string().cuid(), workspaceId: z.string().cuid() }))
.mutation(async ({ ctx, input }) => {
// Vérifier propriété idea → workspace → user (multi-tenant)
// Vérifier que llmEnrichFailed === true
// Appeler fetch vers /api/llm/enrich (ou service directement)
// Retourner { queued: true }
})
[x] Subtask 5.2 : Le handler vérifie que le workspace appartient à ctx.session.user.id (via Workspace.ownerId)
[x] Subtask 5.3 : Retourner { queued: true } immédiatement — l'enrichissement s'exécute en arrière-plan
[x] Task 6 : Mise à jour src/env.js (AC: #1)
[x] Subtask 6.1 : Ajouter NEXT_PUBLIC_APP_URL dans la section server de src/env.js (pour les appels internes de idea.submit) :
NEXT_PUBLIC_APP_URL: z.string().url().optional().default('http://localhost:3000'),
[x] Subtask 6.2 : Ajouter dans runtimeEnv : NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL
[x] Task 7 : Tests (AC: #1, #2, #3, #4, #5, #6)
src/app/api/llm/enrich/route.test.ts avec Vitest — mocker db, enrichIdea{ skipped: true, reason: "idea_limit_reached" }{ skipped: true, reason: "llm_limit_reached" }llmEnrichFailed = true en basesrc/server/services/llm.enrich.test.ts — tester enrichIdea avec mock OpenAInullnullDéclenchement asynchrone — fire-and-forget :
idea.submit : void fetch(...) sans await — la réponse { ideaId } est retournée immédiatement au clientapi/webhooks/email/route.ts) : utiliser after() de next/server (Next.js 15 stable) pour exécuter après la réponse 200after() est disponible dans les Route Handlers Next.js 15 — import : import { after } from 'next/server'after() utilise waitUntil sous le capot, garantissant l'exécution même après la réponseSécurité multi-tenant — CRITIQUE :
idea.workspaceId === input.workspaceId AVANT l'appel LLMGestion des limites tier (NFR11, NFR12) :
isLlmAllowed est dans ~/lib/tier (Pattern établi Story 2.3) — réutiliserdb.idea.count({ where: { workspaceId, llmEnrichedAt: { not: null } } }) — plus précis que de compter toutes les idéesOpenAI structured outputs — implémentation recommandée :
const completion = await openai.chat.completions.create(
{
model: "gpt-4o-mini",
messages: [
{ role: "system", content: systemPrompt },
{ role: "user", content: userPrompt },
],
response_format: { type: "json_object" }, // garantit un JSON valide
max_tokens: 400,
temperature: 0.3, // plus déterministe pour les scores
},
{ signal: controller.signal }
);
const content = completion.choices[0]?.message?.content;
if (!content) return null;
const parsed = JSON.parse(content);
const validated = enrichResultSchema.safeParse(parsed);
if (!validated.success) return null;
return validated.data;
Timeout — deux niveaux :
enrichIdea (service) → pour les 90% de cas NFR4llmEnrichFailed = true couvre les cas > 30s (la route peut avoir un timeout Vercel de 30s en prod)vercel.json si > 10s nécessaire pour la route /api/llm/enrichIdempotence de la route /api/llm/enrich :
llmEnrichedAt !== null → retourner { success: true, enriched: false, alreadyDone: true } sans ré-appeler OpenAICoût LLM — estimation par idée (NFR10) :
Langue du contenu généré :
document_output_language: French de la config)llmDomain et llmAiType sont en français dans les promptsPattern services/llm.ts — extension :
generateContextualExamples (Story 2.3)enrichIdea dans le même fichier pour cohérence, OU créer services/llm.enrich.ts si le fichier devient trop long (> 150 lignes)generateContextualExamplesconst { OpenAI } = await import("openai")) — même pattern que Story 2.3Retry manuelle (FR21) — procédure idea.retryEnrich :
idea.ts router (comme toutes les mutations sur les idées)fetch('/api/llm/enrich', ...) — pas d'import direct du service pour éviter les dépendances circulaires avec le contexte Next.jscreateWorkspaceProcedure n'est pas encore créé — utiliser protectedProcedure avec validation manuelle du workspace.ownerId| Fichier | Action |
|---|---|
src/server/services/llm.ts |
Modifier — ajouter enrichIdea(), interfaces EnrichIdeaParams, EnrichIdeaResult |
src/app/api/llm/enrich/route.ts |
Créer — Route Handler POST /api/llm/enrich |
src/app/api/llm/enrich/route.test.ts |
Créer — tests Vitest route handler |
src/server/services/llm.enrich.test.ts |
Créer — tests Vitest service enrichIdea |
src/server/api/routers/idea.ts |
Modifier — ajouter fire-and-forget + procédure retryEnrich |
src/app/api/webhooks/email/route.ts |
Modifier — ajouter after() pour déclencher enrichissement |
src/env.js |
Modifier — ajouter NEXT_PUBLIC_APP_URL côté serveur |
import { db } from "~/server/db" (singleton — jamais new PrismaClient())import { z } from "zod" — validation input ET output LLMthrow new TRPCError({ code: "UNAUTHORIZED", message: "..." }) dans les procéduresNextResponse.json({ error: "..." }, { status: 4xx }) — pas de TRPCErrorworkspaceId — voir anti-pattern dans architecture.mdLe schéma Prisma est déjà complet pour cette story. Tous les champs LLM ont été anticipés lors de la Story 1.2 :
// Sur le modèle Idea (déjà en base) :
llmTitle String?
llmDomain String?
llmAiType String?
llmExplanation String? @db.Text
llmScoreImpact Int?
llmScoreFeasibility Int?
llmScoreUrgency Int?
llmEnrichedAt DateTime?
llmEnrichFailed Boolean @default(false)
Aucun prisma migrate requis pour cette story.
Story 2.3 (exemples contextuels) — patterns à réutiliser :
const controller = new AbortController() + setTimeout(() => controller.abort(), LLM_TIMEOUT_MS)const { OpenAI } = await import("openai") (évite les problèmes SSR)isLlmAllowed(workspace) de ~/lib/tier — réutiliser tel quelllmCallsThisMonth avec { increment: 1 } — même patternStory 2.5 (webhook email) — patterns à réutiliser :
await db.$transaction(async (tx) => { ... })after() import de next/server pour fire-and-forget post-response (dans les Route Handlers)Story 2.4b (seed) — patterns de test :
vi.mock("~/server/db", () => ({ db: { idea: { update: mockUpdate } } }))vi.mock("openai", () => ({ OpenAI: vi.fn().mockImplementation(() => ({ chat: { completions: { create: mockCreate } } })) }))Contributeur soumet formulaire
→ idea.submit (tRPC) → idée créée en DB
→ void fetch('/api/llm/enrich', { ideaId, workspaceId }) [fire-and-forget]
→ réponse { ideaId } retournée au client immédiatement
[async, ~2-10s plus tard]
→ POST /api/llm/enrich reçu
→ validation ownership idea → workspace
→ vérification limites tier
→ enrichIdea(params) appelé avec AbortController 8s
→ OpenAI gpt-4o-mini JSON mode → parse + Zod validate
→ db.$transaction([idea.update(llmFields), workspace.update(llmCallsThisMonth++)])
→ { success: true, enriched: true }
[si LLM échoue/timeout]
→ db.idea.update({ llmEnrichFailed: true })
→ { success: false, enriched: false }
isLlmAllowed() réutilisésrc/app/api/llm/enrich/ est prévu dans l'arborescence cible de architecture.md (§ Project Structure — api/llm/enrich/route.ts)src/server/services/llm.ts contient déjà generateContextualExamples — étendre ce fichierapi/llm/enrich/, services/llm.ts, components/idea/ScoreSlider.tsx (pour Story 3.4)src/server/api/routers/idea.ts exporte déjà le router idea — ajouter retryEnrich sans rompre les exports existants{{agent_model_name_version}}
enrichIdea() dans services/llm.ts avec interfaces, AbortController 8s, prompt JSON, validation ZodPOST /api/llm/enrich avec validation ownership, limites tier (NFR11/NFR12), idempotence, transaction atomiqueidea.submit (tRPC)after() depuis webhook email pour enrichissement post-réponseidea.retryEnrich (protectedProcedure, vérification owner + llmEnrichFailed)NEXT_PUBLIC_APP_URL dans src/env.js (section client — requis pour jsdom/Vitest)after dans webhook test pour éviter fetch en test| # | Sév | Finding | Correction appliquée |
|---|---|---|---|
| 1 | High | retryEnrich : ownership check après llmEnrichFailed → information disclosure |
Workspace ownerId vérifié AVANT exposition du statut llmEnrichFailed |
| 2 | High | enrichIdea : catch silencieux, aucun log serveur (violation architecture) |
console.error avec ideaId + raison (timeout vs erreur API) |
| 3 | Med | Webhook : req.method !== "POST" dead code App Router |
Bloc 405 supprimé |
| 4 | Med | Route enrich : request.json() parse fail → 500 au lieu de 400 |
Try/catch interne sur request.json() → 400 |
| 5 | Low | Test succès : expect(mockTransaction).toHaveBeenCalled() insuffisant |
Assertions sur mockIdeaUpdate et mockWorkspaceUpdate avec données exactes |
| 6 | Low | Prompt LLM "5 mots" vs Zod "8 mots" pour llmTitle |
Prompt aligné sur contrainte Zod réelle : "8 mots maximum" |