3-6-recherche-dans-le-backlog-fr27.md 18 KB

Story 3.6 : Recherche dans le backlog (FR27)

Status: done

Story

En tant que Transformateur, je veux rechercher des idées par mots-clés dans le backlog, afin de retrouver rapidement une idée spécifique parmi plusieurs soumissions.

Acceptance Criteria

  1. Given je suis sur la vue liste du backlog (Story 3.2) When je consulte la zone de filtres Then un champ de recherche par mots-clés est visible (placeholder : "Rechercher une idée…") And le champ est positionné en tête du panneau de filtres existant

  2. Given je saisis des mots-clés dans le champ de recherche When j'ai saisi au moins 1 caractère (avec debounce ~300 ms) Then la liste du backlog est filtrée pour n'afficher que les idées dont le titre (llmTitle), la description (problemDescription), le domaine (llmDomain), le type IA (llmAiType) ou le département (department) contient les mots-clés (insensible à la casse) And la recherche se combine avec les filtres existants (statut, domaine, contributeur, non-prioritaires) via logique AND

  3. Given le champ de recherche contient du texte When je consulte le champ Then un bouton "Effacer" (icône ×) est visible pour réinitialiser la recherche uniquement And cliquer sur "Effacer" vide le champ et restaure la liste complète (les autres filtres restent actifs)

  4. Given aucune idée ne correspond à la recherche When la requête retourne 0 résultats alors qu'un searchQuery est actif Then un message "Aucune idée ne correspond à votre recherche." s'affiche avec un lien "Effacer la recherche" And ce message est distinct de l'empty state "aucune idée dans le workspace" (Story 3.2)

  5. Given le champ de recherche est vide When je consulte le backlog Then toutes les idées correspondant aux autres filtres actifs s'affichent (comportement identique à Story 3.2)

  6. Given un utilisateur non propriétaire du workspace appelle idea.getBacklog avec searchQuery When la procédure tRPC est appelée Then une erreur UNAUTHORIZED est retournée (ownership check inchangé — comportement identique à Story 3.2)

Tasks / Subtasks

  • [x] Task 1 : Ajouter searchQuery au schéma input getBacklog dans src/server/api/routers/idea.ts (AC: #2, #5, #6)

    • Subtask 1.1 : Ajouter searchQuery: z.string().optional() à l'objet .input() de getBacklog
    • [x] Subtask 1.2 : Dans ctx.db.idea.findMany, ajouter la clause OR de recherche multi-champs quand searchQuery est défini et non vide :

      ...(input.searchQuery?.trim() && {
      OR: [
      { llmTitle: { contains: input.searchQuery, mode: "insensitive" } },
      { problemDescription: { contains: input.searchQuery, mode: "insensitive" } },
      { llmDomain: { contains: input.searchQuery, mode: "insensitive" } },
      { llmAiType: { contains: input.searchQuery, mode: "insensitive" } },
      { department: { contains: input.searchQuery, mode: "insensitive" } },
      ],
      }),
      
    • [x] Subtask 1.3 : Vérifier que la logique AND avec les filtres existants est préservée — la clause OR s'ajoute aux autres propriétés du where Prisma (isolation implicite par AND)

  • [x] Task 2 : Ajouter l'état de recherche et le debounce dans src/components/backlog/BacklogListView.tsx (AC: #2, #5)

    • Subtask 2.1 : Ajouter const [searchInput, setSearchInput] = useState("") — valeur brute de l'input
    • Subtask 2.2 : Ajouter const [searchQuery, setSearchQuery] = useState("") — valeur débouncée (~300 ms)
    • [x] Subtask 2.3 : Implémenter le debounce via useEffect :

      useEffect(() => {
      const timer = setTimeout(() => setSearchQuery(searchInput), 300);
      return () => clearTimeout(timer);
      }, [searchInput]);
      
    • [x] Subtask 2.4 : Passer searchQuery: searchQuery || undefined à api.idea.getBacklog.useQuery (ne pas transmettre une string vide)

  • [x] Task 3 : Créer le composant SearchInput dans src/components/backlog/SearchInput.tsx (AC: #1, #3)

    • Subtask 3.1 : Composant "use client" — props : value: string, onChange: (v: string) => void
    • Subtask 3.2 : Input shadcn avec icône Search (lucide-react) absolue à gauche — largeur min w-[220px]
    • Subtask 3.3 : Bouton icône X visible quand value !== "" — appelle onChange("") au clic, aria-label="Effacer la recherche"
    • Subtask 3.4 : Attributs : placeholder="Rechercher une idée…", aria-label="Rechercher dans le backlog", type="search"
  • [x] Task 4 : Intégrer SearchInput dans BacklogListView.tsx et gérer l'empty state "pas de résultats" (AC: #1, #4)

    • Subtask 4.1 : Placer <SearchInput value={searchInput} onChange={setSearchInput} /> dans la div des filtres, avant <BacklogFilters>
    • Subtask 4.2 : Gérer les deux empty states :
    • Si searchQuery !== "" et ideas.length === 0 → afficher message "Aucune idée ne correspond à {searchQuery}" avec lien "Effacer la recherche"
    • Si searchQuery === "" et ideas.length === 0 → afficher <BacklogEmptyState workspaceId={workspaceId} /> (existant — Story 3.2)
  • [x] Task 5 : Tests (AC: #2, #5, #6)

    • Subtask 5.1 : Créer ou étendre src/server/api/routers/idea.getBacklog.test.ts (Vitest)
    • Subtask 5.2 : Test : searchQuery défini → findMany appelé avec clause OR contenant les 5 champs
    • Subtask 5.3 : Test : searchQuery absent (undefined) → findMany appelé sans clause OR
    • Subtask 5.4 : Test : searchQuery vide "" ou après .trim() → pas de clause OR (trim guard)
    • Subtask 5.5 : Test : searchQuery + filterStatus → les deux conditions sont présentes dans le where
    • Subtask 5.6 : Créer src/components/backlog/SearchInput.test.tsx (Vitest + RTL)
    • Subtask 5.7 : Test SearchInput : saisie → onChange appelé avec la valeur
    • Subtask 5.8 : Test SearchInput : bouton × absent quand value === "", présent quand value !== ""
    • Subtask 5.9 : Test SearchInput : clic sur × → onChange("") appelé

Dev Notes

Architecture & Décisions techniques

Approche retenue : enrichir getBacklog (Option A — in-place)

Plutôt que de créer un router séparé (searchBacklog), searchQuery est ajouté au getBacklog existant :

  • Combinaison native avec les filtres existants (AND implicite Prisma)
  • Un seul call réseau par render
  • Invalidation React Query cohérente avec les mutations Story 3.5
  • Aucune migration Prisma requise

Pattern Prisma OR search (mode insensitive) :

// Dans getBacklog — après la construction de statusWhere et des autres filtres
const ideas = await ctx.db.idea.findMany({
  where: {
    workspaceId: input.workspaceId,
    ...(Object.keys(statusWhere).length > 0 && { status: statusWhere }),
    ...(input.filterDomain && { llmDomain: input.filterDomain }),
    ...(input.filterContributor && { contributorEmail: input.filterContributor }),
    // Nouveau : recherche multi-champs (AND avec les filtres ci-dessus)
    ...(input.searchQuery?.trim() && {
      OR: [
        { llmTitle: { contains: input.searchQuery, mode: "insensitive" } },
        { problemDescription: { contains: input.searchQuery, mode: "insensitive" } },
        { llmDomain: { contains: input.searchQuery, mode: "insensitive" } },
        { llmAiType: { contains: input.searchQuery, mode: "insensitive" } },
        { department: { contains: input.searchQuery, mode: "insensitive" } },
      ],
    }),
  },
  orderBy: buildBacklogOrderBy(input.sortBy, input.sortOrder),
  // ... select, take: 200
});

Note Prisma : mode: "insensitive" est supporté nativement par PostgreSQL (Neon eu-central-1) — aucune configuration supplémentaire requise. Ne pas utiliser search (Prisma full-text search) qui nécessite une extension PostgreSQL @@fulltext et un index dédié — contains + mode: "insensitive" est suffisant pour MVP avec ≤ 200 idées (NFR5).

Debounce côté client :

// BacklogListView.tsx
const [searchInput, setSearchInput] = useState("");   // valeur brute de l'input
const [searchQuery, setSearchQuery] = useState("");   // valeur après debounce ~300 ms

useEffect(() => {
  const timer = setTimeout(() => setSearchQuery(searchInput), 300);
  return () => clearTimeout(timer);
}, [searchInput]);

// Dans useQuery
const { data: ideas, isLoading, isError } = api.idea.getBacklog.useQuery({
  workspaceId,
  sortBy,
  sortOrder,
  filterStatus: filters.filterStatus.length > 0 ? filters.filterStatus : undefined,
  filterDomain: filters.filterDomain || undefined,
  filterContributor: filters.filterContributor || undefined,
  includeNotPriority: filters.includeNotPriority,
  searchQuery: searchQuery || undefined, // ne pas envoyer "" — inutile et pollue le cache React Query
});

Composant SearchInput :

"use client";

import { Search, X } from "lucide-react";
import { Input } from "~/components/ui/input";

interface SearchInputProps {
  value: string;
  onChange: (value: string) => void;
}

export function SearchInput({ value, onChange }: SearchInputProps) {
  return (
    <div className="relative min-w-[220px]">
      <Search className="absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
      <Input
        type="search"
        value={value}
        onChange={(e) => onChange(e.target.value)}
        placeholder="Rechercher une idée…"
        aria-label="Rechercher dans le backlog"
        className="h-8 pl-8 pr-7 text-xs"
      />
      {value && (
        <button
          onClick={() => onChange("")}
          className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground"
          aria-label="Effacer la recherche"
          type="button"
        >
          <X className="h-3.5 w-3.5" />
        </button>
      )}
    </div>
  );
}

Positionnement dans BacklogListView :

{/* Zone filtres + recherche — dans la div flex-col gap-4 existante */}
<div className="flex flex-col gap-2">
  <SearchInput value={searchInput} onChange={setSearchInput} />
  <BacklogFilters
    workspaceId={workspaceId}
    filters={filters}
    onFiltersChange={setFilters}
  />
</div>

Empty state "pas de résultats de recherche" (inline) :

{!isLoading && !isError && ideas?.length === 0 && (
  searchQuery ? (
    <div className="rounded-lg border bg-white p-8 text-center text-sm text-muted-foreground">
      Aucune idée ne correspond à{" "}
      <strong>&ldquo;{searchQuery}&rdquo;</strong>.{" "}
      <button
        onClick={() => setSearchInput("")}
        className="text-violet-600 hover:underline"
        type="button"
      >
        Effacer la recherche
      </button>
    </div>
  ) : (
    <BacklogEmptyState workspaceId={workspaceId} />
  )
)}

Schéma Prisma — aucune migration requise

La recherche s'effectue sur des colonnes existantes du modèle Idea :

Champ Type Prisma Rationale
llmTitle String? Titre normalisé LLM — terme le plus court et précis
problemDescription String @db.Text Description brute du contributeur — mots du métier
llmDomain String? Domaine métier (ex. "RH", "Supply Chain")
llmAiType String? Type IA (ex. "Automatisation", "Prédiction")
department String Département saisi par le contributeur

Non inclus dans la recherche :

  • contributorEmail — couvert par le filtre contributeur existant dans BacklogFilters
  • llmExplanation — texte long, bruit pour la recherche rapide MVP

Index existants utilisés : @@index([workspaceId, status]) — performant pour les filtres combinés. Le contains PostgreSQL sur text est un scan séquentiel sur la partition workspace (acceptable ≤ 200 idées — NFR5).

Aucun prisma migrate requis pour cette story.

Structure des fichiers

Fichier Action
src/server/api/routers/idea.ts Modifier — ajouter searchQuery?: z.string().optional() à getBacklog + clause OR dans findMany
src/components/backlog/SearchInput.tsx Créer — input search avec icône + bouton ×
src/components/backlog/BacklogListView.tsx Modifier — état searchInput/searchQuery, debounce useEffect, intégration SearchInput, empty state recherche
src/components/backlog/SearchInput.test.tsx Créer — tests RTL composant
src/server/api/routers/idea.getBacklog.test.ts Créer ou étendre — tests Vitest searchQuery

Conventions architecture à respecter

  • Ownership check AVANT toute opération : déjà présent dans getBacklog → aucune modification requise (AC #6 couvert automatiquement)
  • Filtrer par workspaceId : inchangé — workspaceId reste le premier critère du where
  • Zod input validation : z.string().optional() — ne pas utiliser .min(1) pour permettre la valeur vide côté client (guard dans le code applicatif avec ?.trim())
  • React Query : re-fetch automatique quand les paramètres de useQuery changent — le debounce suffit à limiter les appels
  • Tests co-localisés : *.test.ts ou *.test.tsx à côté du fichier testé
  • Toast : non requis pour cette story (lecture seule, pas de mutation)

Apprentissages des stories précédentes

Story 3.2 (vue liste backlog) :

  • api.idea.getBacklog.useQuery est configuré dans BacklogListView avec les paramètres des filtres — ajouter searchQuery suit exactement le même pattern
  • React Query re-déclenche la requête automatiquement dès que searchQuery change (valeur débouncée)
  • Le take: 200 (NFR5) s'applique après le filtre searchQuery → les 200 premiers résultats de la recherche

Story 3.5 (gestion des statuts) :

  • utils.idea.getBacklog.invalidate() (sans paramètres) invalide toutes les queries getBacklog du workspace, y compris celles avec searchQuery — cohérent après changement de statut
  • StatusSelect continue de fonctionner dans les lignes de résultats de recherche sans modification

Story 3.4 (fiche détaillée) :

  • La recherche ne concerne pas getById — uniquement getBacklog
  • Les champs llmTitle, llmDomain, llmAiType peuvent être null (idées avec llmEnrichFailed: true) — Prisma contains sur un champ null retourne false silencieusement, comportement attendu

Story 3.1 (enrichissement LLM) :

  • Les idées avec llmEnrichFailed: true n'ont pas de llmTitle, llmDomain, llmAiType — leur problemDescription et department restent dans le scope de recherche → ces idées restent trouvables par la description ou le département

NFR concernés

  • NFR5 : backlog < 3 s pour ≤ 200 idées — contains PostgreSQL est performant sur ce volume avec l'index existant @@index([workspaceId, status])
  • NFR14 : isolation workspace — ownership check inchangé, workspaceId filtre en premier

References

  • [Source: epics.md#Story 3.6 — Recherche dans le backlog (FR27)]
  • [Source: prd.md#FR27 — recherche par mots-clés dans le backlog]
  • [Source: architecture.md#Implementation Patterns — protectedProcedure, ownership check, tRPC errors, naming conventions]
  • [Source: architecture.md#Pattern Examples — getIdeas avec workspaceId filter]
  • [Source: architecture.md#API Naming Conventions — procédures tRPC camelCase]
  • [Source: prisma/schema.prisma — model Idea (fields: llmTitle, problemDescription, llmDomain, llmAiType, department)]
  • [Source: src/server/api/routers/idea.ts — getBacklog procedure (Story 3.2), IDEA_STATUS_VALUES, patterns filtres]
  • [Source: src/components/backlog/BacklogListView.tsx — état filters, useQuery getBacklog, structure layout]
  • [Source: src/components/backlog/BacklogFilters.tsx — pattern filtres combinés, import Select shadcn]
  • [Source: src/components/backlog/BacklogEmptyState.tsx — empty state existant à distinguer du "pas de résultats de recherche"]
  • [Source: implementation-artifacts/3-2-vue-liste-du-backlog-fr22-fr24.md — patterns table, React Query, empty state]
  • [Source: implementation-artifacts/3-5-gestion-des-statuts-et-statut-non-prioritaire-fr26.md — invalidation React Query, architecture patterns]

Change Log

  • 2026-02-28 : Implémentation complète Story 3.6 (FR27) — recherche par mots-clés dans le backlog. Backend : searchQuery dans getBacklog avec clause OR multi-champs. Frontend : SearchInput, debounce 300 ms, empty state "pas de résultats". 8 tests ajoutés (4 getBacklog, 4 SearchInput).
  • 2026-02-28 : Post code-review — corrections H1/H2/M1/M2/M3 : suppression bouton webkit natif ([&::-webkit-search-cancel-button]:hidden), effacement immédiat sans flash (setSearchQuery direct), max(200) sur searchQuery (Zod), test whitespace-trimming, reset global filtres + recherche via onSearchReset callback dans BacklogFilters. 325/325 tests verts.

Dev Agent Record

Agent Model Used

Composer (Cursor)

Debug Log References

Completion Notes List

  • ✅ Task 1 : searchQuery ajouté au schéma input getBacklog + clause OR multi-champs (llmTitle, problemDescription, llmDomain, llmAiType, department) avec mode: "insensitive" PostgreSQL
  • ✅ Task 2 : État searchInput/searchQuery + debounce 300 ms via useEffect dans BacklogListView
  • ✅ Task 3 : Composant SearchInput créé (icône Search, bouton ×, placeholder, aria-labels)
  • ✅ Task 4 : SearchInput intégré avant BacklogFilters ; empty state "pas de résultats" distinct du BacklogEmptyState
  • ✅ Task 5 : 4 tests getBacklog (searchQuery) + 4 tests SearchInput (RTL)
  • Tous les 324 tests passent, aucune régression

File List

  • aimpact-hub/src/server/api/routers/idea.ts (modifié)
  • aimpact-hub/src/server/api/routers/idea.getBacklog.test.ts (modifié)
  • aimpact-hub/src/components/backlog/SearchInput.tsx (créé)
  • aimpact-hub/src/components/backlog/SearchInput.test.tsx (créé)
  • aimpact-hub/src/components/backlog/BacklogListView.tsx (modifié)