---
page: keywords
sous-page: overview
route: /keywords/overview
statut: draft
version: 0.1
transverse-liées: [reservoir-data-model (TBD), conventions, i18n, design-system]
date: 2026-06-03
---

# CdC — `keywords/overview`

> **Dashboard en lecture** qui agrège toute la section `keywords` pour un site. Point d'entrée + **drill-down** vers les sous-pages. Aucune donnée propre : il lit des agrégats.

## 1. Objectif

Donner, en un écran, l'**état de la section keywords** d'un site (santé du Reservoir, opportunités, couverture pays, cadence de planning) et **quoi faire ensuite** (actions suggérées), avec **drill-down** vers la sous-page concernée, déjà filtrée.

## 2. Périmètre

- **Dans** : KPIs agrégés (lecture), trending, **couverture par pays** (résumé de la matrice `recherche`), **backlog d'opportunités**, cadence/avancement `planning`, activité récente, **actions suggérées**, **drill-down**.
- **Hors** : toute **écriture** (elle se fait dans les sous-pages). Les actions suggérées **renvoient** vers la sous-page concernée.

## 3. User stories *(persona : consultant SEO)*

- En arrivant sur un site, je **vois l'état** de mes keywords d'un coup d'œil.
- Je repère **quoi faire en priorité** (actions suggérées) et j'y vais en un clic.
- Je clique un KPI → j'atterris sur la **sous-page filtrée** correspondante.

## 4. Fonctionnalités

- F1 — **Sélecteur de site global** (isolation `site_id`).
- F2 — **KPIs Reservoir** : total keywords, répartition par **statut** (idea/watch/active/archived), par **intent**, par **thème**.
- F3 ⭐ — **Trending now** : keywords *watch* qui **décollent** (signal de tendance).
- F4 — **Couverture par pays** : résumé de la matrice `recherche` (présence / **trous**).
- F5 — **Backlog d'opportunités** : top keywords par **score d'opportunité** non encore planifiés.
- F6 — **Planning** : **cadence** (page-plans/période) + **avancement** (planifié / en prod / en ligne).
- F7 — **Activité récente** : derniers imports, dernières activations.
- F8 ⭐ — **Actions suggérées** : « 3 *watch* à re-checker · 5 opportunités à planifier · 2 trous pays à combler · 1 saisonnier à planifier maintenant » → chaque action **ouvre la sous-page ciblée** (quick-action selon `conventions` R2).
- F9 — **Drill-down** : cliquer une carte → sous-page filtrée sur le segment.

## 5. UI / écrans

- **Grille de cartes** (`card-base` / `card-feature`), lecture seule, avec **mini-charts/sparklines**.
- **Actions suggérées** exécutables via **quick-action** (modal de confirmation) ou navigation — voir `_transverse/conventions.md` (R2).
- États vide / chargement / erreur ; responsive : grille → pile en mobile. Tokens `design.md`.

## 6. Données & actions

- **Affiché** : agrégats (KPIs, couverture, backlog, planning, activité, suggestions).
- **Actions** : naviguer / drill-down, déclencher une action suggérée (qui ouvre la sous-page concernée).

## 7. Modèle de données

- **Aucune table propre.** Lit des **agrégats** sur `keyword`, `keyword_target`, `page_plan`, `import_job` (vues/agrégats serveur). Réf `_transverse/reservoir-data-model` (TBD).

## 8. API Hono

- `GET /sites/:siteId/keywords/dashboard` *(tous les agrégats)*
- `GET /sites/:siteId/keywords/suggested-actions`
- `GET /sites/:siteId/keywords/recent-activity`

> Routes **préfixées par `siteId`**. Agrégats **cachés** (lecture fréquente).

## 9. Capacités requises *(fonctionnel — mapping modules TBD)*

Agrégation/lecture multi-entités · calcul des **actions suggérées** (règles : watch à re-checker, opportunités à planifier, trous pays, saisonniers) · cache.

## 10. Tools / capacités MCP

- `kw_dashboard` (read) · `kw_suggested_actions` (read) · `kw_recent_activity` (read)

> Privé vs public-limité : **TBD**.

## 11. i18n

- UI localisée (clés). Réf `_transverse/i18n.md` (TBD).

## 12. Qualité *(réf. fiches des 128 par slug)*

- **Perf** : agrégats **pré-calculés/cachés**, `cache-control`, `core-web-vitals`.
- **A11y** : cartes et quick-actions **opérables clavier**, `keyboard-navigation`, `focus-indicators`.
- **Sécu** : isolation **par site** ; `cookie-attributes`, auth.
- **Indexation** : app privée → `meta-robots` (noindex).

## 13. Critères d'acceptation

- [ ] Les KPIs reflètent exactement le Reservoir du **site sélectionné**.
- [ ] Une **action suggérée** ouvre la **bonne sous-page**, **filtrée** sur le segment concerné.
- [ ] Cliquer un KPI (ex. « watch ») draille vers `reservoir` filtré sur ce statut.
- [ ] « Trending now » liste bien des *watch* dont la série mensuelle monte.
- [ ] Le **switch de site** réinitialise tout le dashboard.

## 14. Dépendances & risques · questions ouvertes

- **Dépend de** : `reservoir`, `recherche`, `planning`, `export-import` (sources des agrégats), `_transverse/reservoir-data-model`, `_transverse/conventions`.
- **Risques** : coût des agrégats en temps réel (→ pré-calcul/cache) ; pertinence des règles d'actions suggérées.
- **Questions ouvertes** : fréquence de rafraîchissement des agrégats (temps réel vs cache court) ? règles exactes de priorisation des actions suggérées ?