--- page: keywords sous-page: reservoir route: /keywords/reservoir statut: draft version: 0.2 transverse-liées: [reservoir-data-model (TBD), sources, i18n, design-system] date: 2026-06-03 --- # CdC — `keywords/reservoir` > **Reservoir** (clin d'œil à *Reservoir Dogs*) = réservoir de recherche / staging de mots-clés. **Ce n'est PAS du rank-tracking** (ça, c'est `keywords/suivi`). ## 1. Objectif Offrir une **source unique** de tous les keywords d'un site, **conservés durablement même à 0 d'intérêt actuel**, pour pouvoir : filtrer/organiser par langue et thématique, **dupliquer/traduire entre langues**, **re-vérifier périodiquement** via Google et d'autres outils si un keyword décolle, et **activer** ceux qui deviennent intéressants → en faire des pages. Le Reservoir est un **réservoir d'opportunités latentes**, pas un suivi de positions. ## 2. Périmètre - **Dans** : conservation longue durée des keywords par site/langue/thème ; statuts (cycle de vie) ; dédup/merge multi-sources ; métriques consolidées **taggées par source** ; **série mensuelle de volume** (tendance/saisonnalité) ; intents, content-type, SERP features, tags, notes ; filtres/recherche/tri ; vues sauvegardées ; duplication inter-langues ; déclenchement d'export (re-check) et d'activation. - **Hors** : découverte de *nouveaux* keywords → `keywords/recherche`. Rank-tracking (positions) → `keywords/suivi`. Détail des connecteurs d'import/export → `keywords/export-import` + `_transverse/sources.md`. Création effective des pages → `contenu/planning`. ## 3. User stories *(persona : consultant SEO multi-sites / multi-langues)* - En tant que consultant, je **switche de site** et je retrouve un Reservoir, des thématiques et des keywords **propres à ce site uniquement**. - Je **garde un keyword à 0 de volume** aujourd'hui, en statut *watch*, pour le re-vérifier plus tard. - Je **re-exporte mes keywords *watch* vers Google** (Keyword Planner) pour voir si le volume monte, puis je ré-importe les nouvelles valeurs. - Quand un keyword décolle, je le passe ***active*** et je l'envoie à `contenu/planning` pour créer une page. - Je **duplique un keyword (ou un lot) vers une autre langue** pour décliner une thématique. - Je **filtre par intent / statut / tendance / thème / source** et je sauvegarde la vue. - Je vois, pour un même keyword, les **métriques de plusieurs outils côte à côte** (Mangools, Ahrefs, Google…). ## 4. Fonctionnalités **Périmètre & navigation** - F1 — **Sélecteur de site global** : tout l'écran est filtré par `site_id` (isolation stricte). - F2 — Dimension **langue** (filtre + colonne) ; **arbre de thématiques** propre au site. **Table & exploration** - F3 — Table dense des keywords : `terme · langue · thème · statut · intent · volume · KD · CPC · croissance% · tendance(sparkline) · sources · maj`. - F4 — Filtres : langue, thème, **statut**, intent, source, content-type, SERP features, tags, **plages** (volume / KD / CPC / croissance %). Recherche plein-texte (inclure/exclure). Tri multi-colonnes. - F5 — **Vues / segments sauvegardés** (par site). **Différenciateurs ⭐** - F6 ⭐ — **Détection de tendance** à partir de la série mensuelle : *rising / falling / saisonnier / spike* + score « trending soon » ; **sparkline** par ligne ; mini-graphe annuel dans le détail. - F7 ⭐ — **Watchlist + re-check programmé** : statut *watch* + planification d'une re-vérif (export vers Google/outil) ; comparaison de l'évolution ; alerte quand un *watch* décolle. - F8 ⭐ — **Workflow d'activation** : `idea → watch → active → archived` (+ `discarded`) ; passer *active* propose l'envoi vers `contenu/planning`. - F9 ⭐ — **Multi-sources miscibles** : métriques par source côte à côte sur un même keyword + **données brutes conservées** (ré-export fidèle). - F10 ⭐ — **Duplication / traduction inter-langues** : dupliquer un keyword (ou un lot) vers une autre langue, traduction auto optionnelle du terme, **liaison via `concept`**. - F11 ⭐ — **Score d'opportunité** : combine faible KD × croissance × intent × volume → priorisation. **Édition & lots** - F12 — Édition inline (statut, intent, thème, tags, note). - F13 — Bulk : assigner statut/intent/thème/tags, **dupliquer vers langue**, exporter sélection, archiver. **Détail keyword** - F14 — Panneau latéral : métriques par source, graphe série mensuelle, historique des statuts, traductions liées (concept). ## 5. UI / écrans - **DataTable shadcn virtualisée** (volumétrie potentiellement élevée) + barre de filtres/recherche (`search-pill`) + bulk-actions bar. - **Sélecteur de site** proéminent (le contexte de toute la page). - **Sheet latéral** pour le détail keyword (métriques multi-sources + graphe). - Sparkline inline dans la table ; badges de statut et d'intent (tokens `design.md` : `badge-*`). - États **vide / chargement / erreur** explicites ; responsive : table → cards en mobile. ## 6. Données & actions - **Affiché** : table + agrégats d'en-tête (total, par statut, par intent) + détail. - **Actions** : changer de site, filtrer/trier/rechercher, éditer (inline + bulk), merger, dupliquer vers langue, changer de statut, programmer un re-check, exporter, activer (→ contenu), archiver/discarder. ## 7. Modèle de données *(esquisse — détail dans `_transverse/reservoir-data-model.md`, TBD)* ``` site(id, nom, domaine, locales[]) theme(id, site_id, nom, parent_id?) keyword(id, site_id, language, term, term_norm, theme_id?, status, intents[], content_types[], serp_features[], tags[], note, concept_id?, opportunity_score?, created, updated) keyword_source_metric(id, keyword_id, source, location, vol_last_known, vol_12m, vol_6m, vol_3m, cpc, ppc, kd, growth_pct, captured_at, raw JSONB) -- 1 ligne par (keyword × source × snapshot) keyword_volume_point(keyword_id, source, month, volume) -- série mensuelle (tendance/saisonnalité) concept(id, site_id, label) -- relie les traductions d'un même mot-clé source(code, label, mapping_profile) -- mapping colonnes source → canonique (miscibilité) ``` - **Statuts** : `idea` · `watch` · `active` · `archived` · `discarded`. - **Unicité** d'un keyword : `(site_id, language, term_norm)`. - **Miscibilité** : un *mapping profile* par source (voir `_transverse/sources.md`) + conservation du `raw` (ré-export sans perte) + métriques **taggées par source**. - PG pour le relationnel/agrégats ; **SurrealDB candidat** pour le graphe `concept`/variantes. - **À trancher** : granularité « site » = domaine / sous-domaine / projet ? Stockage série mensuelle en table dédiée vs JSONB ? ## 8. API Hono - `GET /sites/:siteId/keywords` (filtres + pagination + tri) - `GET /sites/:siteId/keywords/:id` - `PATCH /sites/:siteId/keywords/:id` - `POST /sites/:siteId/keywords/bulk` (statut/intent/thème/tags/archive) - `POST /sites/:siteId/keywords/:id/duplicate` (→ autre langue) - `POST /sites/:siteId/keywords/merge` - `POST /sites/:siteId/keywords/:id/recheck` (programme un export/re-vérif) - `POST /sites/:siteId/keywords/:id/activate` (→ contenu/planning) - `GET /sites/:siteId/keywords/aggregates` - `GET /sites/:siteId/keywords/views` · `POST …/views` (vues sauvegardées) > Toutes les routes sont **préfixées par `siteId`** — l'isolation par site est structurelle, pas un simple filtre. ## 9. Capacités requises *(fonctionnel — mapping modules TBD)* Stockage multi-dimensions scopé site · dédup/normalisation de termes · agrégation multi-sources · ingestion/conservation de série temporelle · détection de tendance · recherche/filtre performants · duplication/traduction inter-langues · planification de re-check (file d'attente). ## 10. Tools / capacités MCP - `kw_reservoir_query` (read) · `kw_reservoir_get` (read) - `kw_reservoir_update` (write) · `kw_reservoir_bulk` (write) - `kw_duplicate_language` (write) · `kw_merge` (write/destructive) - `kw_trend` (read — renvoie le signal de tendance) · `kw_opportunity` (read — score) - `kw_export` (read) · `kw_activate` (write — pousse vers contenu) > Périmètre privé vs public-limité : **TBD** (step MCP). ## 11. i18n - UI localisée (clés). Réf `_transverse/i18n.md` (TBD) et les fiches `i18n` de `docs/specification/`. - **La langue du keyword est une dimension *data*** (par site), distincte de la langue de l'UI. - La duplication inter-langues peut s'appuyer sur une traduction auto du terme (à valider : moteur ?). ## 12. Qualité *(réf. fiches des 128 par slug)* - **Perf** : `core-web-vitals`, `cache-control` — table virtualisée, pagination serveur, index PG sur `(site_id, language, term_norm)`. - **A11y** : `data-tables`, `keyboard-navigation`, `form-labels`, `focus-indicators`, `touch-target-size`. - **Sécu** : `cookie-attributes`, auth ; isolation des données **par site** (un site ne doit jamais lire le Reservoir d'un autre). - **Indexation** : app privée → `meta-robots` (noindex). ## 13. Critères d'acceptation - [ ] Switcher de site change **tout** le contenu ; aucun keyword d'un autre site n'apparaît jamais. - [ ] Filtrer par langue + statut + plage de volume renvoie le sous-ensemble exact, paginé. - [ ] Un keyword importé de 2 sources affiche **une ligne de métriques par source** dans le détail, sans écraser l'autre. - [ ] Ré-exporter un keyword reproduit fidèlement les données brutes de la source d'origine (`raw`). - [ ] Dupliquer un keyword vers une autre langue crée une entrée liée par `concept`, sans casser l'unicité `(site, langue, terme)`. - [ ] Un keyword *watch* dont la série mensuelle monte déclenche le signal « trending » et (si programmé) une alerte. - [ ] Passer un keyword en *active* propose la création d'une page dans `contenu/planning`. - [ ] La sparkline et le graphe de détail reflètent la série mensuelle importée. ## 14. Dépendances & risques · questions ouvertes - **Dépend de** : `_transverse/reservoir-data-model` (TBD), `_transverse/sources` (mapping profiles), `keywords/export-import` (connecteurs), `contenu/planning` (activation). - **Risques** : stratégie de dédup/normalisation (singulier/pluriel, accents, casse) ; volumétrie de la série mensuelle ; fiabilité de la détection de tendance ; qualité de la traduction auto. - **Questions ouvertes** : - Granularité « site » = domaine / sous-domaine / projet ? - Série mensuelle : table dédiée vs JSONB ? - Moteur de re-check « Google » : Keyword Planner (API Ads) + Search Console + Trends — lequel pilote l'alerte ? - Score d'opportunité : pondération exacte des facteurs ?