2-3-exemples-ia-contextuels-a-louverture-du-formulaire-fr14-ia1-fr14-ia2.md 6.4 KB

Story 2.3: Exemples IA contextuels à l'ouverture du formulaire (FR14-IA1, FR14-IA2)

Status: done

Story

En tant que Contributeur, je veux voir 2 à 3 exemples de cas d'usage IA contextuels à l'ouverture du formulaire, afin de reconnaître mes problèmes comme des opportunités IA.

Acceptance Criteria

  1. Given j'ouvre le formulaire de soumission (/submit/[workspaceSlug]) When le système appelle le LLM avec le secteur et la taille du workspace (et département si connu) Then 2 à 3 exemples en langage métier (sans acronymes NLP, OCR, ML, LLM, API) sont affichés en moins de 3 secondes And si dépassement ou échec LLM, des exemples génériques pré-calculés s'affichent immédiatement (NFR3)

  2. Given le secteur du workspace n'est pas configuré When j'ouvre le formulaire Then des exemples génériques PME sont affichés avec un indicateur "Exemples génériques" (NFR17)

  3. Given j'ai sélectionné mon département (via DepartmentPicker) When les exemples sont chargés Then les exemples sont filtrés/contextualisés par fonction (RH, Finance, etc.) si le LLM le supporte

Tasks / Subtasks

  • [ ] Task 1 : Service LLM et génération d'exemples (AC: #1, #2)

    • Subtask 1.1 : Créer src/server/services/llm.ts — fonction generateContextualExamples(sector?, companySize?, department?) retournant 2-3 exemples
    • Subtask 1.2 : Intégration OpenAI (ou compatible) — prompt en français, instruction explicite : pas d'acronymes (NLP, OCR, ML, LLM, API) dans le corps des exemples
    • Subtask 1.3 : Définir exemples génériques pré-calculés (fallback) dans src/lib/fallbackExamples.ts — 3 exemples PME sans jargon
    • Subtask 1.4 : Timeout 3 secondes — si dépassé, retourner fallback immédiatement
  • [ ] Task 2 : Route Handler API /api/llm/examples (AC: #1, #2, #3)

    • Subtask 2.1 : Créer src/app/api/llm/examples/route.ts — POST avec body { workspaceSlug, department? }
    • Subtask 2.2 : Récupérer workspace par slug (sector, companySize) ; valider workspace existe
    • Subtask 2.3 : Appeler generateContextualExamples ; en cas d'erreur ou timeout → retourner fallback
    • Subtask 2.4 : Vérifier limite LLM tier Free (NFR12) — si dépassée, retourner fallback sans appeler l'API
  • [ ] Task 3 : Composant ExamplePill et panneau exemples (AC: #1, #2)

    • Subtask 3.1 : Créer src/components/form/ExamplePill.tsx — affichage d'un exemple, cliquable pour pré-remplir (optionnel Story 2.3 — focus affichage)
    • Subtask 3.2 : Créer src/components/form/ExamplesPanel.tsx — charge exemples via fetch /api/llm/examples, skeleton 3s max, fallback si erreur
    • Subtask 3.3 : Badge "Exemples génériques" si sector null (NFR17)
    • Subtask 3.4 : Intégrer ExamplesPanel dans IdeaSubmissionForm (remplacer le placeholder actuel)
  • [ ] Task 4 : Passer sector/companySize/department au chargement (AC: #1, #3)

    • Subtask 4.1 : Modifier page submit pour charger workspace avec sector, companySize
    • Subtask 4.2 : ExamplesPanel reçoit workspaceSlug, sector, companySize ; appelle API avec department quand DepartmentPicker change
    • Subtask 4.3 : Déclencher rechargement exemples quand department change (debounce 300ms)
  • [ ] Task 5 : Tests (AC: #1, #2)

    • Subtask 5.1 : Test service llm — mock OpenAI, vérifier format réponse (2-3 exemples, pas de jargon)
    • Subtask 5.2 : Test route /api/llm/examples — workspace invalide 404, fallback si erreur
    • Subtask 5.3 : Test composant ExamplesPanel — skeleton, affichage exemples, fallback

Dev Notes

Contexte technique

  • Story 2.2 : IdeaSubmissionForm existe avec layout 2 colonnes ; panneau droit placeholder "disponible prochainement". DepartmentPicker déjà présent.
  • Workspace : sector (distribution, industrie, services, sante, finance), companySize (Int). Si null → contexte générique.
  • Architecture : Route Handlers pour LLM (/api/llm/examples), pas tRPC (appel public sans auth).
  • NFR3 : < 3s ; fallback immédiat si timeout ou erreur. Jamais bloquer le contributeur.
  • NFR12 : 50 appels LLM/mois tier Free. Vérifier llmCallsThisMonth avant d'appeler.
  • NFR17 : Indicateur "Exemples génériques" si sector non configuré.

Exemples génériques (fallback)

// src/lib/fallbackExamples.ts
export const FALLBACK_EXAMPLES = [
  "Automatiser la saisie de données répétitives depuis des documents ou emails",
  "Détecter des anomalies dans les processus pour anticiper les problèmes",
  "Résumer automatiquement de longs documents pour gagner du temps",
];

Service LLM — structure

// src/server/services/llm.ts
export async function generateContextualExamples(params: {
  sector?: string | null;
  companySize?: number | null;
  department?: string | null;
}): Promise<string[]> {
  // Prompt: générer 2-3 exemples en langage métier, SANS acronymes NLP/OCR/ML/LLM/API
  // Timeout 2500ms pour laisser marge avant 3s
}

Architecture Compliance

  • Multi-tenant : Valider workspace par slug ; pas de données inter-workspace.
  • Fallback : Jamais d'erreur exposée au contributeur — toujours un résultat (contextuel ou générique).
  • Limite LLM : Incrémenter llmCallsThisMonth après appel réussi (ou dans service).

File Structure Requirements

Fichier Action
src/server/services/llm.ts Créer — generateContextualExamples
src/lib/fallbackExamples.ts Créer — FALLBACK_EXAMPLES
src/app/api/llm/examples/route.ts Créer — Route Handler POST
src/components/form/ExamplesPanel.tsx Créer
src/components/form/ExamplePill.tsx Créer (optionnel clic pré-remplissage)
src/components/form/IdeaSubmissionForm.tsx Modifier — intégrer ExamplesPanel
src/app/(public)/submit/[workspaceSlug]/page.tsx Modifier — passer sector, companySize
.env.example Modifier — OPENAI_API_KEY

References

  • [Source: epics.md#Story 2.3]
  • [Source: prd.md#FR14-IA1, FR14-IA2]
  • [Source: prd.md#NFR3, NFR12, NFR17]
  • [Source: architecture.md#api/llm/examples]
  • [Source: ux-design-specification.md#ExamplePill]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

File List