Voici le cahier des charges fonctionnel et technique consolidé. Il structure l'ensemble de votre vision : un outil de Keyword Intelligence ultra-performant, pensé pour les experts, qui garantit une intégrité totale de la donnée, de l'extraction jusqu'au Kanban de rédaction. # Cahier des Charges : Module "Data-to-Content Flow" ## 1. Vision et Objectifs Créer une plateforme unifiée regroupant la puissance de Semrush, Ahrefs et Mangools. L'objectif principal est d'établir un flux de travail ininterrompu et qualitatif reliant la recherche de mots-clés à la planification éditoriale. Le système refuse l'automatisation de masse au profit d'un workflow d'expert ("Tour de Contrôle") où chaque contenu est adossé à un reverse engineering précis des SERPs et à un brief validé manuellement. ## 2. Architecture Technique Cible Le socle technique est orienté haute performance et traitement de données lourdes : - **Front-end & Framework :** Next.js (versions 15/16) exploitant les React Server Components (RSC) pour le rendu initial rapide des tableaux de données. - **Backend & Data Processing :** Moteur d'agrégation basé sur DuckDB et Hono pour traiter et croiser rapidement les métriques massives issues des différentes sources primaires. - **Mutations & UI :** Utilisation des Server Actions Next.js couplées à des mises à jour optimistes côté client (`useOptimistic`) pour une interface fluide. - **Modèle de Données (Ciblage) :** L'entité `Keyword` porte l'état de ciblage en natif (ex: tableau d'objets `targets: [{ locale: "fr-FR", status: "planned" }]`), évitant les tables de jointure complexes et optimisant le fetch initial. ## 3. Le Pipeline Éditorial (Workflow par étape) ### Étape 1 : Découverte et Ciblage (`/keywords/recherche`) - **Vue Matrice :** Utilisation du composant `coverage-matrix.tsx` pour afficher les mots-clés en lignes et les pays cibles en colonnes. - **Action Serveur :** Clic sur une cellule pour passer le statut de "Non ciblé" à "Planifié" (badge `planned`). - **Persistance :** L'état éphémère actuel est remplacé par une Server Action (`updateKeywordTargetAction`) qui met à jour la base DuckDB et revalide le chemin pour synchroniser le cache. ### Étape 2 : Le Sas de Validation ("Chambre de Briefing" - `/keywords/planning`) Cette page n'est plus un stub mais devient le backlog stratégique de l'expert. - **Filtrage par défaut :** N'affiche que les mots-clés ayant le statut `planned` dans au moins un pays. - **Enrichissement SERP & On-Page :** Déclenchement des scripts d'extraction (utilisation de Firecrawl pour le reverse engineering des concurrents) pour rapatrier les données de trafic, backlinks, et structure on-page (JSON-LD, Img Alt). - **Validation IA/Humain :** L'expert utilise Gemini pour itérer sur la data brute et générer un brief parfait. - **Intégration :** Import manuel du brief `.txt` finalisé dans la section dédiée **Briefs YTG** (panneau par pays avec objectifs, sujets, questions, ton). ### Étape 3 : La Vue de Dispatch (Nouvelle route `/keywords/dispatch/[id]`) Une interface de validation plein écran, large et aérée, remplaçant la modale basique, divisée en trois zones : 1. **Indicateurs de Qualité :** Affichage clair des pastilles tri-state (SERP `ok`, On-page `ok`, Brief `ok`) certifiant que la préparation est complète. 2. **Tableau de Bord SERP :** Affichage large des concurrents crawlés sans scroll horizontal contraint. 3. **Paramétrage Kanban :** Champs d'édition pour le Titre, la Date d'échéance et l'Assigné (rédacteur). - **Action de Bascule :** Le bouton "Envoyer en production" déclenche l'action `updateContentStatusAction`, convertit le mot-clé en `ContentItem` et ferme la vue. ### Étape 4 : La Production (`/content/planning`) - **Réception :** Le `ContentItem` atterrit automatiquement dans la colonne Kanban `brief`. - **Exécution :** Le rédacteur ouvre la carte, constate que les indicateurs (SERP, On-page, Brief) sont au vert (`ok`), et dispose de toutes les informations pour rédiger. ## 4. Correctifs Techniques et UX à Implémenter (Post-Audit) Pour soutenir ce nouveau workflow, les points de friction identifiés lors de l'audit doivent être résolus : **Performance et Robustesse :** - **Virtualisation du Réservoir Backlink :** Implémentation d'une solution de fenêtrage (virtualized list) sur `/backlink/reservoir` pour gérer le rendu du volume important de sources (~380 lignes) sans dégrader les performances côté client. - **Gestion des Erreurs :** Mise en place d'une infrastructure globale de notifications (toasts) pour remplacer les mutations silencieuses (`catch {}`) sur les actions Keywords et Backlinks. **Accessibilité et Ergonomie (A11y) :** - **Navigation Clavier SERP :** Ajout des attributs `role`, `tabIndex`, et `onKeyDown` sur les lignes du panneau des concurrents SERP (`serp-panel.tsx`) pour garantir l'opérabilité sans souris. - **État des URLs :** Synchronisation des filtres et de la pagination avec l'URL sur les vues tables pour permettre le deep-linking et le partage de vues spécifiques entre collaborateurs. - **Groupement Sémantique :** Ajout des attributs `role="group"` et `aria-pressed` sur les contrôles segmentés de la page Profil pour les lecteurs d'écran. C'est le cœur du réacteur. Pour que l'application reste extrêmement réactive sous Next.js 15/16 sans surcharger le serveur, il faut une maîtrise absolue du cycle de vie de la donnée, de son état initial jusqu'à sa publication. Voici le détail complet du "flow parfait", étape par étape, en décomposant les mutations (Server Actions + `useOptimistic`) et la promotion d'état au sein de votre base de données DuckDB. ### Phase 1 : L'Intention (Réservoir ➔ Recherche) Le point de départ est la masse brute, qui devient soudainement une cible stratégique. - **Localisation :** Matrice de la page `/keywords/recherche`. - **Action Utilisateur :** L'expert clique sur la cellule croisant un mot-clé (ex: "stratégie netlinking") et un pays (ex: "fr-FR") pour la passer de "Non ciblé" à "Planifié". - **Mutation :** Appel de `updateKeywordTargetAction(keywordId, 'fr-FR', 'planned')`. Pour l'UI, un hook `useOptimistic` bascule instantanément la cellule visuellement sans attendre le retour serveur. - **Promotion d'état (DuckDB) :** L'entité `Keyword` est mise à jour. *Avant :* `targets: []` *Après :* `targets: [{ locale: "fr-FR", status: "planned" }]` - **Impact UI :** Le `revalidatePath('/keywords')` s'exécute. Le mot-clé est désormais éligible pour basculer dans le sas de planification. ### Phase 2 : L'Enrichissement & Le Sas (Recherche ➔ Planning) Le mot-clé est "réservé". Il faut maintenant lui donner la profondeur de données nécessaire pour la rédaction. - **Localisation :** La "Chambre de Briefing" sur `/keywords/planning`. - **Action Utilisateur :** L'expert lance le reverse engineering des SERPs via vos scripts (ex: via une API Hono qui orchestre Firecrawl), puis importe le brief `.txt` finalisé. - **Mutation :** Upload des données via `uploadSerpDataAction` et `uploadBriefAction`. - **Promotion d'état :** L'objet `Keyword` s'enrichit massivement : *Avant :* Mots-clés bruts + `targets`. *Après :* Ajout des payloads `serpFeatures`, de l'analyse des concurrents (images, JSON-LD), et de l'objet `briefs: { "fr-FR": "contenu du brief.txt" }`. - **Impact UI :** Les pastilles "tri-state dots" (SERP, On-page, Brief) évoluent d'abord de `none` (rouge) à `partial` (ambre), puis passent définitivement à `ok` (vert). Le feu est vert. ### Phase 3 : L'Incubation (Planning ➔ Dispatch) C'est l'étape de vérification humaine. Pas de changement d'état en base, mais une agrégation visuelle. - **Localisation :** La nouvelle vue `/keywords/dispatch/[id]`. - **Action Utilisateur :** Clic sur "Préparer l'article" depuis le sas. - **État en mémoire :** C'est une vue en lecture (RSC fetch) qui compile la totalité de l'objet `Keyword` (les indicateurs au vert, les concurrents extraits, le brief YTG validé) dans une interface plein écran confortable. - **Action de préparation :** L'expert saisit le Titre définitif, la Date d'échéance et sélectionne un Assigné. ### Phase 4 : La Transmutation (Dispatch ➔ Content Kanban) C'est le moment critique où une "Data" (le mot-clé) engendre un "Livrable" (l'article). - **Localisation :** Bouton "Envoyer en production" dans la vue de Dispatch. - **Action Utilisateur :** L'expert valide la préparation. - **Mutation :** Appel de `createContentItemAction(payload)` qui fait la passerelle entre les deux univers du système. - **Promotion d'état :** 1. **Création :** Une nouvelle entité `ContentItem` est générée dans la table dédiée, liée au `keywordId` : `{ id: "C-123", keywordId: "K-456", title: "...", assignee: "...", dueDate: "...", status: "brief" }`. 2. **Mise à jour :** L'état du ciblage du mot-clé passe potentiellement de `planned` à `in_production` (selon la granularité de votre suivi). - **Impact UI :** Fermeture de la vue Dispatch, redirection ou toast de confirmation. ### Phase 5 : Le Pipeline Éditorial (Kanban ➔ Online) La donnée brute est devenue un ticket de travail piloté par des statuts. - **Localisation :** Le tableau Kanban `/content/planning`. - **Action Utilisateur :** Le rédacteur drag & drop la carte Kanban ou modifie l'état via la Sheet de l'article. - **Mutation :** `updateContentStatusAction(contentId, newStatus)`. - **Promotion d'état :** Le champ `status` de `ContentItem` évolue strictement selon la séquence `CONTENT_STATUSES` : `brief` ➔ `writing` ➔ `review` ➔ `published`. - **Impact UI :** - La carte navigue de colonne en colonne. - Une fois passée en `published`, l'entité quitte le domaine du Kanban et alimente la page `/content/online` en lecture seule, où le système commence à réconcilier ce contenu avec les futures métriques GSC (impressions, clics, CTR, position moyenne). La boucle est bouclée.