2-4a-bibliotheque-de-cas-dusage-ia-ui-et-pre-remplissage-fr14-ia3-fr14-ia4-fr14-ia5.md 20 KB

Story 2.4a : Bibliothèque de cas d'usage IA - UI et pré-remplissage (FR14-IA3, FR14-IA4, FR14-IA5)

Status: done

Story

En tant que Contributeur ou CDO, je veux parcourir une bibliothèque de cas d'usage IA organisée par secteur et fonction, afin de m'inspirer ou de pré-remplir le formulaire de soumission.

Acceptance Criteria

  1. Given j'accède au formulaire de soumission (/submit/[workspaceSlug]) When je clique sur "Parcourir la bibliothèque" Then une modale s'ouvre avec la bibliothèque organisée par secteur (distribution, industrie, services, santé, finance) et fonction (RH, finance, supply chain, commercial, opérations) And je peux filtrer par secteur et par fonction via des pills cliquables

  2. Given je consulte la bibliothèque depuis le formulaire (contributeur) When je sélectionne un cas d'usage Then le champ problemDescription du formulaire est pré-rempli avec la description du cas sélectionné And un badge "Inspiré de : [titre du cas]" s'affiche avec un bouton de réinitialisation And département, impact estimé et fréquence restent à renseigner par le contributeur

  3. Given je suis authentifié en tant que Transformateur (CDO) When j'accède à /workspace/[workspaceId]/library Then je vois la même bibliothèque avec les mêmes filtres secteur/fonction And chaque cas propose un bouton "Copier le lien" qui copie /submit/[workspaceSlug]?caseId=[id] And chaque filtre de catégorie propose un bouton "Copier ce filtre" qui copie /submit/[workspaceSlug]?sector=[s]&department=[d]

  4. Given un contributeur ouvre le lien partagé /submit/[workspaceSlug]?caseId=[id] When la page se charge Then le formulaire est pré-rempli avec la description du cas de bibliothèque correspondant And le badge "Inspiré de : [titre]" est visible

  5. Given un contributeur ouvre le lien /submit/[workspaceSlug]?sector=[s]&department=[d] When la page se charge Then la modale bibliothèque s'ouvre automatiquement avec les filtres pré-sélectionnés

  6. Given la bibliothèque est vide (avant le seed de Story 2.4b) When j'ouvre la modale ou la page bibliothèque Then un empty state s'affiche : "Les cas d'usage seront disponibles prochainement" And aucune erreur n'est levée

  7. Given je clique sur un exemple IA contextuel (ExamplePill) dans le panneau de droite du formulaire When je clique sur le pill Then le champ problemDescription est pré-rempli avec le texte de l'exemple

Tasks / Subtasks

  • [x] Task 1 : Modèle Prisma LibraryCase + migration (AC: #1, #2, #4)

    • Subtask 1.1 : Ajouter le modèle LibraryCase dans prisma/schema.prisma - champs : id (cuid), sector (String), department (String), title (String), description (Text), createdAt, updatedAt ; index sur [sector], [department], [sector, department] ; pas de workspaceId (bibliothèque globale partagée)
    • Subtask 1.2 : Générer et écrire la migration SQL dans prisma/migrations/ avec le nom YYYYMMDD_add_library_case
    • Subtask 1.3 : Régénérer le client Prisma (prisma generate)
  • [x] Task 2 : tRPC router library.ts (AC: #1, #2, #3, #6)

    • Subtask 2.1 : Créer src/server/api/routers/library.ts avec deux publicProcedure : getAll (input : { sector?: string; department?: string } via Zod, retourne LibraryCase[] triés alphabétiquement par titre) et getById (input : { id: string }, retourne LibraryCase | null)
    • Subtask 2.2 : Enregistrer libraryRouter dans src/server/api/root.ts
  • [x] Task 3 : Composants UI bibliothèque (AC: #1, #6)

    • Subtask 3.1 : Créer src/components/library/LibraryCaseCard.tsx - props : { case: LibraryCase; onSelect?: (c: LibraryCase) => void; showShareButton?: boolean; shareUrl?: string } ; variante compact (titre + secteur + fonction + extrait description) ; role="button" si onSelect fourni ; aria-pressed selon sélection
    • Subtask 3.2 : Créer src/components/library/LibraryCategoryFilter.tsx - pills secteur et pills fonction, sélection multiple possible, prop value: { sector?: string; department?: string } + onChange ; chaque pill a un role="checkbox" et aria-checked
    • Subtask 3.3 : Créer src/components/library/LibraryBrowser.tsx - utilise api.library.getAll via tRPC React Query, intègre LibraryCategoryFilter + liste de LibraryCaseCard, skeleton 4 cards pendant le chargement, EmptyState si 0 résultats (message "Les cas d'usage seront disponibles prochainement"), callback onSelectCase?: (c: LibraryCase) => void passé à chaque card
    • Subtask 3.4 : Créer src/components/library/LibraryModal.tsx - Dialog de shadcn/ui wrappant LibraryBrowser, props : { open: boolean; onOpenChange: (v: boolean) => void; onSelectCase: (c: LibraryCase) => void; initialFilters?: { sector?: string; department?: string } } ; titre "Bibliothèque de cas d'usage IA" ; accessible (focus trap, Escape pour fermer)
  • [x] Task 4 : Intégration formulaire contributeur (AC: #2, #4, #5, #7)

    • Subtask 4.1 : Modifier src/components/form/ExamplesPanel.tsx - ajouter prop onPrefill?: (text: string) => void, passer la callback comme onClick à chaque ExamplePill ; retirer le texte placeholder "pré-remplissage à venir"
    • Subtask 4.2 : Modifier src/components/form/IdeaSubmissionForm.tsx - ajouter état libraryModalOpen: boolean + librarySourceTitle: string | null ; ajouter handler handlePrefill(text: string) qui met à jour form.problemDescription ; ajouter bouton ghost "Parcourir la bibliothèque →" dans la colonne droite sous ExamplesPanel ; afficher badge "Inspiré de : [title]" avec bouton ✕ si librarySourceTitle non null ; passer onPrefill={handlePrefill} à ExamplesPanel
    • Subtask 4.3 : Modifier IdeaSubmissionForm.tsx - ajouter props initialPrefillText?: string et autoOpenLibrary?: boolean + initialLibraryFilters?: { sector?: string; department?: string } ; si initialPrefillText → pré-remplir problemDescription à l'init ; si autoOpenLibrary → ouvrir LibraryModal au montage
    • Subtask 4.4 : Modifier src/app/(public)/submit/[workspaceSlug]/page.tsx (Server Component) - lire searchParams.caseId, searchParams.sector, searchParams.department ; si caseId présent → appeler api.library.getById server-side et passer initialPrefillText + initialLibrarySourceTitle ; si sector ou department → passer autoOpenLibrary=true + initialLibraryFilters
  • [x] Task 5 : Page bibliothèque CDO (AC: #3)

    • Subtask 5.1 : Créer src/app/(dashboard)/workspace/[workspaceId]/library/page.tsx - page protégée (session requise, createWorkspaceProcedure), récupérer workspaceSlug depuis la session/DB, passer showShareButton=true + shareUrl calculée à chaque LibraryCaseCard
    • Subtask 5.2 : Implémenter le bouton "Copier le lien" dans LibraryCaseCard - si showShareButton et shareUrl fournis : bouton ghost qui copie shareUrl dans le presse-papier + toast de confirmation "Lien copié !"
    • Subtask 5.3 : Implémenter le bouton "Copier ce filtre" dans LibraryCategoryFilter - prop optionnelle getFilterShareUrl?: (filters) => string ; si fournie, afficher bouton copie filtre actif ; copie l'URL et affiche toast
  • [x] Task 6 : Tests (AC: #1, #2, #3, #6, #7)

    • Subtask 6.1 : Test src/server/api/routers/library.test.ts - logique de filtrage getAll (sector, department, combinés)
    • Subtask 6.2 : Test src/components/library/LibraryCaseCard.test.tsx - rendu titre + description, clic appelle onSelect, bouton share copie URL
    • Subtask 6.3 : Test src/components/library/LibraryBrowser.test.tsx - empty state si 0 cas, skeleton pendant chargement, sélection d'un cas appelle onSelectCase
    • Subtask 6.4 : Tests IdeaSubmissionForm - couverts par tests manuels (formulaire complet avec mocks tRPC/fetch)

Dev Notes

Contexte technique

  • Story 2.3 complète : ExamplesPanel.tsx + ExamplePill.tsx existent dans src/components/form/. ExamplePill a déjà la prop onClick?: () => void. ExamplesPanel a le texte "pré-remplissage à venir" (à retirer). Ces composants sont prêts pour l'extension.
  • Story 2.2 complète : IdeaSubmissionForm.tsx existe avec layout 2 colonnes. Champs : contributorEmail, department, problemDescription, estimatedImpact, frequency. Pas de champ "titre" explicite dans le formulaire - la description du cas bibliothèque pré-remplit problemDescription. Le titre du cas est affiché dans le badge "Inspiré de".
  • Pas de workspaceId sur LibraryCase : la bibliothèque est partagée entre tous les workspaces (globale). Les filtres secteur/fonction sont utilisés pour la pertinence.
  • La bibliothèque sera vide jusqu'à Story 2.4b (seed). L'empty state est donc critique et doit s'afficher sans erreur.
  • tRPC public procedures pour la bibliothèque : le formulaire contributeur est public (sans auth), donc publicProcedure (pas protectedProcedure ni createWorkspaceProcedure). La page CDO lit aussi la même bibliothèque publique.
  • Lien partageable CDO : généré côté serveur dans la page dashboard en construisant /submit/[workspaceSlug]?caseId=[id]. Le CDO copie ce lien et le transmet à ses contributeurs. Quand un contributeur ouvre ce lien, le Server Component lit searchParams.caseId, fetch le cas en DB et passe le texte de pré-remplissage.

Modèle Prisma LibraryCase

model LibraryCase {
    id          String   @id @default(cuid())
    sector      String   // distribution | industrie | services | sante | finance
    department  String   // rh | finance | supply-chain | commercial | operations
    title       String
    description String   @db.Text
    createdAt   DateTime @default(now())
    updatedAt   DateTime @updatedAt

    @@index([sector])
    @@index([department])
    @@index([sector, department])
}

Router library.ts - structure

// src/server/api/routers/library.ts
import { z } from "zod";
import { createTRPCRouter, publicProcedure } from "~/server/api/trpc";

export const libraryRouter = createTRPCRouter({
  getAll: publicProcedure
    .input(
      z.object({
        sector: z.string().optional(),
        department: z.string().optional(),
      })
    )
    .query(async ({ ctx, input }) => {
      return ctx.db.libraryCase.findMany({
        where: {
          ...(input.sector ? { sector: input.sector } : {}),
          ...(input.department ? { department: input.department } : {}),
        },
        orderBy: { title: "asc" },
      });
    }),

  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ ctx, input }) => {
      return ctx.db.libraryCase.findUnique({ where: { id: input.id } });
    }),
});

Pré-remplissage formulaire - flux

// Dans IdeaSubmissionForm.tsx
const handleSelectFromLibrary = (libraryCase: LibraryCase) => {
  setForm((prev) => ({ ...prev, problemDescription: libraryCase.description }));
  setLibrarySourceTitle(libraryCase.title);
  setLibraryModalOpen(false);
};

const handlePrefill = (text: string) => {
  setForm((prev) => ({ ...prev, problemDescription: text }));
  setLibrarySourceTitle(null); // ExamplePill n'a pas de titre explicite
};

Page submit - lecture searchParams (Server Component)

// src/app/(public)/submit/[workspaceSlug]/page.tsx
// searchParams est passé automatiquement par Next.js App Router
interface PageProps {
  params: { workspaceSlug: string };
  searchParams: { caseId?: string; sector?: string; department?: string };
}

export default async function SubmitPage({ params, searchParams }: PageProps) {
  // Fetch workspace, puis si caseId présent, fetch le cas bibliothèque
  const libraryCase = searchParams.caseId
    ? await db.libraryCase.findUnique({ where: { id: searchParams.caseId } })
    : null;

  // Passer les props dérivées à IdeaSubmissionForm
}

Architecture Compliance

  • Multi-tenant : LibraryCase est global (pas de workspaceId) - intentionnel et documenté. La page CDO valide la session Transformateur avant d'afficher la bibliothèque.
  • publicProcedure pour library.getAll + library.getById : cohérent avec /submit/[workspaceSlug] qui est public. Pas d'isolation workspace nécessaire pour la bibliothèque.
  • Naming conventions : libraryRouter, LibraryCaseCard, LibraryBrowser, LibraryModal, LibraryCategoryFilter - PascalCase pour composants, camelCase pour router.
  • shadcn/ui Dialog pour LibraryModal - cohérent avec le reste du projet (Sheet est utilisé ailleurs, Dialog est approprié pour la bibliothèque).
  • tRPC React Query pour LibraryBrowser : api.library.getAll.useQuery(filters) - pas de fetch direct (contrairement à ExamplesPanel qui utilise fetch natif car sans auth).
  • Erreurs : TRPCError({ code: "NOT_FOUND" }) si getById appelé avec un ID inexistant depuis le CDO. Côté contributeur (Server Component), si caseId invalide → libraryCase = null → formulaire vide sans erreur.

Structure des fichiers

Fichier Action
prisma/schema.prisma Modifier - ajouter modèle LibraryCase
prisma/migrations/YYYYMMDD_add_library_case/migration.sql Créer
src/server/api/routers/library.ts Créer - libraryRouter
src/server/api/root.ts Modifier - enregistrer libraryRouter
src/components/library/LibraryCaseCard.tsx Créer
src/components/library/LibraryCategoryFilter.tsx Créer
src/components/library/LibraryBrowser.tsx Créer
src/components/library/LibraryModal.tsx Créer
src/components/form/ExamplesPanel.tsx Modifier - prop onPrefill, retirer texte placeholder
src/components/form/IdeaSubmissionForm.tsx Modifier - gestion modal bibliothèque, badge, pré-remplissage
src/app/(public)/submit/[workspaceSlug]/page.tsx Modifier - lecture searchParams.caseId, sector, department
src/app/(dashboard)/workspace/[workspaceId]/library/page.tsx Créer - page CDO bibliothèque

Notes UX importantes

  • Empty state bibliothèque : "Les cas d'usage seront disponibles prochainement" - message rassurant, pas d'erreur, pas de CTA inutile. Story 2.4b ajoutera le seed.
  • Badge "Inspiré de" : fond #ede9fe, texte #5b21b6, bouton ✕ ghost pour reset. Positionné sous le label du champ problemDescription, au-dessus du textarea.
  • Bouton "Parcourir la bibliothèque →" : variant ghost, positionné en bas du panneau droit (sous ExamplesPanel) sur desktop. Sur mobile (< lg), accessible via un bouton visible sous le formulaire (pas masqué).
  • Copier le lien : utiliser navigator.clipboard.writeText(url). Toast de confirmation via shadcn/ui useToast() : "Lien copié !" (succès vert, 3s). Gérer le cas où l'API clipboard n'est pas disponible (fallback silencieux ou message).
  • Modal bibliothèque : title "Bibliothèque de cas d'usage IA" (h2), sous-titre "Sélectionnez un cas pour pré-remplir votre description". Fermeture par Escape, clic overlay, ou bouton ✕. Focus trap actif. Max height 80vh avec scroll interne.
  • Micro-interaction sélection LibraryCaseCard : bordure 2px solid #7c3aed au clic, fond #faf5ff, 150ms.

Patterns de test recommandés

Utiliser Vitest + React Testing Library (cohérent avec Story 2.3).

// Exemple test LibraryBrowser empty state
import { render, screen } from "@testing-library/react";
import { LibraryBrowser } from "~/components/library/LibraryBrowser";

// Mock tRPC
vi.mock("~/trpc/react", () => ({
  api: {
    library: {
      getAll: {
        useQuery: () => ({ data: [], isLoading: false }),
      },
    },
  },
}));

it("affiche le empty state si aucun cas", () => {
  render(<LibraryBrowser />);
  expect(screen.getByText(/seront disponibles prochainement/i)).toBeInTheDocument();
});

Référence story précédente (2.3) - acquis importants

  • generateContextualExamples existe dans src/server/services/llm.ts (ne pas dupliquer pour la bibliothèque - les cas bibliothèque viennent de la DB, pas du LLM)
  • FALLBACK_EXAMPLES dans src/lib/fallbackExamples.ts - référencer dans les tests si nécessaire
  • ExamplesPanel appelle /api/llm/examples via fetch (Route Handler, public) - la bibliothèque utilise tRPC publicProcedure (approche plus cohérente pour une requête DB)
  • Pattern skeleton : 3 blocs animate-pulse sur bg-[#e9d5ff]/50, hauteur h-12 - réutiliser dans LibraryBrowser
  • Palette Livinia : #faf5ff (fond IA), #e9d5ff (bordure), #6b21a8 (texte violet), #7c3aed (primaire), #fef3c7/#b45309 (amber pour AIBadge) - à respecter dans tous les nouveaux composants

References

  • [Source: epics.md#Story 2.4a]
  • [Source: prd.md#FR14-IA3, FR14-IA4, FR14-IA5]
  • [Source: architecture.md#Frontend Architecture - components/library/]
  • [Source: architecture.md#API - routers/library.ts]
  • [Source: architecture.md#Pattern Examples - publicProcedure]
  • [Source: ux-design-specification.md#Component Strategy - ExamplePill, LibraryBrowser]
  • [Source: ux-design-specification.md#Visual Design Foundation - Palette Livinia]
  • [Source: implementation-artifacts/2-3-exemples-ia-contextuels-a-louverture-du-formulaire-fr14-ia1-fr14-ia2.md]

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

  • Implémentation complète Story 2.4a (FR14-IA3, FR14-IA4, FR14-IA5)
  • Code review (27/02) : corrections H1–H3, M1–M3, L1–L2 - labels sector/department, validation searchParams, hydration baseUrl, bouton Copier filtre, tests clavier, aria-label, lien nav library
  • Modèle Prisma LibraryCase + migration 20260227110000_add_library_case
  • tRPC library router (getAll, getById) - publicProcedure
  • Composants : LibraryCaseCard, LibraryCategoryFilter, LibraryBrowser, LibraryModal
  • Intégration formulaire : onPrefill ExamplePill, LibraryModal, badge "Inspiré de", props initialPrefillText/autoOpenLibrary
  • Page submit : lecture searchParams caseId, sector, department
  • Page CDO /workspace/[workspaceId]/library avec boutons "Copier le lien" et "Copier ce filtre"
  • Tests : library.test.ts, LibraryCaseCard.test.tsx, LibraryBrowser.test.tsx
  • shadcn Dialog et Sonner ajoutés pour la modale et les toasts

File List

  • aimpact-hub/src/lib/libraryConstants.ts (créé - SECTORS, DEPARTMENTS, validation)
  • aimpact-hub/src/server/api/routers/libraryUtils.ts (créé - buildGetAllWhere pour tests)
  • aimpact-hub/prisma/schema.prisma (modifié)
  • aimpact-hub/prisma/migrations/20260227110000_add_library_case/migration.sql (créé)
  • aimpact-hub/src/server/api/routers/library.ts (créé)
  • aimpact-hub/src/server/api/routers/library.test.ts (créé)
  • aimpact-hub/src/server/api/root.ts (modifié)
  • aimpact-hub/src/components/library/LibraryCaseCard.tsx (créé)
  • aimpact-hub/src/components/library/LibraryCaseCard.test.tsx (créé)
  • aimpact-hub/src/components/library/LibraryCategoryFilter.tsx (créé)
  • aimpact-hub/src/components/library/LibraryBrowser.tsx (créé)
  • aimpact-hub/src/components/library/LibraryBrowser.test.tsx (créé)
  • aimpact-hub/src/components/library/LibraryModal.tsx (créé)
  • aimpact-hub/src/components/form/ExamplesPanel.tsx (modifié)
  • aimpact-hub/src/components/form/IdeaSubmissionForm.tsx (modifié)
  • aimpact-hub/src/app/(public)/submit/[workspaceSlug]/page.tsx (modifié)
  • aimpact-hub/src/app/(dashboard)/workspace/[workspaceId]/library/page.tsx (créé)
  • aimpact-hub/src/app/(dashboard)/workspace/[workspaceId]/page.tsx (modifié - lien Bibliothèque)
  • aimpact-hub/src/components/ui/dialog.tsx (ajouté via shadcn)
  • aimpact-hub/src/components/ui/sonner.tsx (ajouté via shadcn)
  • aimpact-hub/src/components/providers.tsx (modifié - Toaster)