• Framework : Next.js 16, TypeScript, React
• Tests : Jest (TDD), Cucumber.js (BDD), Playwright (E2E)
• Hébergement : Vercel
• Dépôt : GitHub `web-malain-et-possible`

Principe fondamental : Séparation claire entre :

• Backend Pur (`utils/`) : Logique métier isolée, testable en CLI, sans dépendance React/Next.js
• Backend Next.js (`app/`, `components/`) : Génération HTML, Server/Client Components

Avantages :

• Testabilité maximale (tests sans mocks complexes)
• Réutilisabilité du code (CLI, tests, composants, API)
• Séparation des préoccupations claire

Convention : Les fichiers du backend pur commencent par un commentaire explicite :

---

Deux commandes uniquement :

• GO US : Commencer une nouvelle User Story (invoque l'agent @US)
• GO NEXT : Avancer d'un cran (revue → corrections/passage à l'étape suivante)

| Agent | Rôle | Périmètre | |-------|------|-----------| | Lead Dev | Orchestration, revue | Ne code pas directement | | US | Reformule en User Story | Critères d'acceptation | | BDD | Écrit scénarios Gherkin | Fichiers `.feature` dans `tests/bdd/` | | TDD-back-end | Logique métier | `utils/` uniquement | | TDD-front-end | Interface utilisateur | `app/`, `components/` | | Designer | CSS uniquement | Hors tunnel, à la demande |

---

RED → GREEN → REFACTOR, un test à la fois, toujours le plus simple possible.

Les tests d'intégration détectent les types présents dans les JSON mais non gérés dans le code. Le test échoue avec un message actionnable : implémenter le type ou le supprimer.

Approche originale : Les TI ne se contentent pas de vérifier — ils :

• Génèrent automatiquement les e2eID manquants dans les fichiers JSON/React
• Mettent à jour `_Pages-Liens-Et-Menus.json` en préservant les métadonnées
• Forcent la décision du développeur (arbitrage obligatoire)

---

Certains tests peuvent échouer pour des raisons antérieures à la session courante. Toujours distinguer les régressions introduites des problèmes préexistants.

• Hash SHA-256 pour les mots de passe (migration depuis MD5)
• Headers CSP, HSTS, X-Content-Type-Options configurés dans `next.config.ts`
• XSS corrigées (plus de `dangerouslySetInnerHTML` pour le contenu utilisateur)
• Validation Path Traversal obligatoire dans `aboutSiteReader.ts` et `api/images/`

---

Dernière mise à jour : 2 février 2026

| Token | Valeur | Usage | |-------|--------|-------| | `--enorme` | 2rem | h1 | | `--grande` | 1.5rem | h2 | | `--moyenne` | 1.25rem | (réservé) | | `--normale` | 1rem | h3, p, listes, liens | | `--petite` | 0.8rem | h4, notes, sous-listes |

Le fichier `constants/canonicalSpec.ts` définit le lien entre chaque propriété des types de contenu et son type hiérarchique. Extrait :

| Nom canonique | Type hiérarchique | Description | |---------------|-------------------|-------------| | `hero.titre` | `--h1` | Titre du hero | | `hero.sousTitre` | `--h2` | Sous-titre du hero | | `hero.description` | `--p` | Description (texte) | | `hero.callToAction` | `--lk` | Lien CTA (aspect bouton) | | `hero.ensavoirplus` | `--lk` | Lien "En savoir plus" | | `titre.texte` | `--h2` | Titre de section | | `profil.titre` | `--h2` | Titre du profil | | `profil.jobTitles` | `--n` | Job titles (note) | | `profil.route` | `--b` | Lien vers profil (bouton) | | `competence.titre` | `--h3` | Titre compétence | | `competence.description` | `--p` | Description compétence | | `temoignage.nom` | `--h3` | Nom du témoin | | `temoignage.fonction` | `--n` | Fonction (note) | | `temoignage.temoignage` | `--p` | Texte témoignage | | `experienceEtApprentissage.description` | `--n` | Description (note) | | `detournementVideo.titre` | `--h2` | Titre détournement | | `detournementVideo.date` | `--n` | Date (note) |

Fonctions utilitaires :

• `getSpecEntriesForType(type)` : retourne les entrées de la spec pour un type de contenu
• `isMarkdownContent(nomCanonique)` : indique si la propriété contient du Markdown
• `typeHierarchiqueToDisplay(type)` : convertit `--h1` → `h1`, `--p` → `p`, etc.

Certaines propriétés des JSON contiennent du texte Markdown qui est parsé et rendu en HTML :

| Type de contenu | Propriété | Markdown supporté | Type hiérarchique | |-----------------|-----------|-------------------|-------------------| | `hero` | `description` | `gras`, `\n` | `--p` | | `texteLarge` | `texte` | `gras`, `\n\n` | `--p` | | `competence` | `description` | `gras`, `lien` | `--p` | | `domaineDeCompetence` | `contenu` | `gras`, `\n` | `--p` | | `temoignage` | `temoignage` | `\n\n` | `--p` | | `experienceEtApprentissage` | `description` | `gras` | `--n` | | `detournementVideo` | `pitch` | `gras` | `--p` |

Syntaxe Markdown supportée :

• `texte` → `<strong>texte</strong>` (gras)
• `texte` → `<em>texte</em>` (italique)
• `texte` → `<a href="url">texte</a>` (lien)
• `\n` → `<br />` (saut de ligne)
• `\n\n` → nouveau `<p>` (paragraphe)

---

• camelCase : un seul mot quand c'est possible (`hero`, `titre`, `video`), sinon plusieurs mots en camelCase (`domaineDeCompetence`, `listeDesPages`, `texteLarge`)
• Préfixe `ui-` : Pour les éléments de structure (layout, wrapper) non définis dans les JSON
• Containers implicites : Chaque propriété a un container `[nomCanonique].cont`

Les conteneurs de listes exposent un attribut data-layout :

| Conteneur | data-layout | Rôle | |-----------|-------------|------| | listeDeProfils | `4 columns x 1 row` | Grille 4 colonnes | | temoignages | `2 columns x N rows` | Grille 2 colonnes | | competences | `3 columns x 1 row` | Grille 3 compétences | | experiencesEtApprentissages | `accordeon, X rows` | Accordéon | | listeDeDetournementsVideo | `X rows` | Liste verticale | | listeDesPages | `draw with page properties` | Rendu dynamique | | droits d'auteur | `tooltip, droits d'auteur` | Popup/tooltip |

---

Structure implicite des pages générées :

• Page = Composant React
• Sections = Blocs de contenu (hero, texte, callToAction...)
• Éléments = Composants individuels

Hiérarchie unifiée :

| Niveau | Markdown | Représentation | |--------|----------|----------------| | H1 | `#` | Chapitre (dossier) | | H2 | `##` | Section (fichier MD) | | H3 | `###` | Partie (dans le fichier) | | H4 | `####` | Sous-partie | | H5 | `#####` | Bloc |

Spécificités via attributs : `typeDeContenu`, `estPrompt`, `estResultatTechnique`

---

Les metadata SEO sont définies dans les JSON de contenu, pas dans les pages. Le helper `metadataBuilder.ts` génère les metadata Next.js.

Les données structurées (Schema.org) sont lues depuis `data/_site-identity.json` :

• `Person` : Identité du propriétaire
• `WebSite` : Description du site
• `BreadcrumbList` : Fil d'Ariane (généré dynamiquement)

---

Dernière mise à jour : 2 février 2026

• Fichier par conversation : `YYYY-MM-DD-NomConversation.md`
• Niveaux H3 → H5 (jamais H1/H2 pour éviter conflits avec la hiérarchie globale)

---

Script `collect-metrics-simple.ts` collectant :

| Catégorie | Métriques | |-----------|-----------| | Tests | Unitaires, Intégration, BDD, E2E (avec durées) | | Couverture | Lines, Statements, Functions, Branches | | Qualité | ESLint errors, Type Coverage (NC actuellement) | | Taille | Fichiers, Lignes, Composants, Pages | | Dépendances | Total, Vulnérabilités | | Performance | Build time, Scores Web (Lighthouse via PageSpeed Insights) |

Scores Web (Lighthouse) : les 4 jauges (Performance, Accessibilité, Bonnes pratiques, SEO) sont remplies par l’API PageSpeed Insights. Sans clé API, le quota est très limité et les scores restent « NC » (jauge à 0). Pour afficher des scores réels : créer une clé sur PageSpeed Insights, puis selon le contexte : en local : définir `PAGESPEED_API_KEY` dans `.env.local` (voir `.env.example`) ; sur Vercel (build = publication) : ajouter la même variable dans le projet Vercel (Settings → Environment Variables), pour que `metrics:collect` (lancé pendant le build) puisse appeler l’API. Mise à jour automatique tous les 7 jours une fois les scores obtenus.

• 100 snapshots maximum (`public/metrics/history.json`)
• Tendances calculées : ↗️ up, ↘️ down, → stable
• Dashboard visuel sur `/metrics`

En local : pour afficher des valeurs à jour (Tests, Couverture, Score Web, Autres indicateurs), exécuter `npm run metrics:collect` avant d’ouvrir la page (ou lancer la commande qui l’inclut, ex. `publie`). Sur Vercel, la collecte est lancée automatiquement avant chaque build.

Les métriques non calculables affichent "NC" au lieu de valeurs fictives.

---

Les scénarios E2E affichés sur la page métriques = nombre de blocs `test('...')` dans `tests/end-to-end/*.spec.ts` (un scénario = une page ouverte + un lien cliqué + retour). En local un seul navigateur (Chromium) est utilisé ; en CI, trois (Chromium, Firefox, WebKit). Le rapport Playwright compte alors des runs (scénarios × navigateurs) : la métrique est normalisée pour afficher le nombre de scénarios (ex. 54), pas le nombre de runs (ex. 162).

Lister les scénarios E2E : `npm run test:e2e:list` (ou `npx playwright test -c playwright.e2e-only.config.ts --list`). Les specs sont dans `tests/end-to-end/` (une par page : accueil, plan-du-site, mes-profils, profils CTO/CPO/COO/Agile, etc.).

Couverture complète de tous les liens cliquables du site.

• Audit automatique du site
• Génération des e2eID manquants
• Arbitrage obligatoire (testé ou exclu explicitement)

• Algorithme glouton optimisé (chaque page visitée une seule fois)
• Enrichissement avec les éléments interactifs
• Mécanismes de fallback (plan du site, logo header)

Pour éviter les conflits entre système déterministe (liens plan du site) et séquentiel :

• Plage 1 : `l600-l749` (150 numéros)
• Plage 2 : `l800-l949` (150 numéros)

---

• Fichier : `_Pages-Liens-Et-Menus.json`
• Régénéré à chaque commit (pre-commit hook)
• Régénéré au build (pour éviter plan vide sur Vercel)

• Toutes les pages du site
• Tous les liens cliquables avec leurs e2eID
• Coordonnées et zones pour les tests E2E

---

• camelCase : un mot si possible (`hero`, `titre`), sinon plusieurs (`domaineDeCompetence`)
• Sous-éléments : reprennent le nom du concept → `.hero .titre`, `.competence .description`
• Préfixe `ui-` : éléments de structure non métier (ex. `.ui-heroCtas`, `.ui-grid`)

---

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `texte` | `--h1` | Titre de la page (dans le header bleu) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `titre` | `--h1` | Titre principal | | `sousTitre` | `--h2` | Sous-titre | | `description` | `--p` | Description (Markdown: gras, \n) | | `callToAction` | `--lk` | Lien CTA (aspect bouton) | | `ensavoirplus` | `--lk` | Lien "En savoir plus" | | `video` | `--v` | Vidéo YouTube (dans hero.droite) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `texte` | `--h2` | Titre de section (bande bleue) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `texte` | `--p` | Bloc de texte (Markdown: gras, \n\n) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `urlYouTube` | `--v` | URL de la vidéo YouTube |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `titre` | `--h2` | Titre du profil | | `jobTitles` | `--n` | Liste des job titles (note) | | `jobTitle` | `--l1` | Job title individuel (liste) | | `slug` | `--m` | Identifiant (métadonnée, non affiché) | | `route` | `--b` | Lien vers le profil (bouton) | | `cvPath` | `--lk` | Lien vers le CV (PDF) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `photo` | `--photo` | Photo du témoin | | `nom` | `--h3` | Nom du témoin | | `fonction` | `--n` | Fonction (note) | | `temoignage` | `--p` | Texte du témoignage (Markdown: \n\n) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `titre` | `--h2` | Titre du domaine | | `contenu` | `--p` | Description (Markdown: gras, \n) | | `auteur` | `--a` | Auteur de la citation (italique) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `titre` | `--h3` | Titre de la compétence | | `description` | `--p` | Description (Markdown: gras, lien) | | `auteur` | `--a` | Auteur de la citation (italique) | | `image.src` | `--img` | Image illustrative | | `image.alt` | `--n` | Texte alternatif (note) | | `bouton.action` | `--lk` | Lien optionnel |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `categorie` | `--m` | Catégorie (métadonnée) | | `description` | `--n` | Description (Markdown: gras) | | `periode` | `--m` | Période (métadonnée) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `action` | `--lk` | Lien (aspect bouton) |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `command` | `--lk` | Lien du bouton |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `titre` | `--h2` | Titre du détournement | | `pitch` | `--p` | Pitch (Markdown: gras) | | `date` | `--n` | Date (note) | | `titreVideoDetournee` | `--h3` | Titre vidéo détournée | | `videoDetournee` | `--v` | Vidéo détournée | | `droitsAuteur` | `--n` | Droits d'auteur (tooltip) | | `linkedin` | `--n` | Lien LinkedIn (note) | | `titreVideoOriginale` | `--h3` | Titre vidéo originale | | `videoOriginale` | `--v` | Vidéo originale |

| Propriété | Type hiérarchique | Description | |-----------|-------------------|-------------| | `page` | `--l1` | Élément de liste (lien vers page) |

---

Indique la mise en page attendue pour les listes et containers :

| Conteneur | data-layout | Comportement | |-----------|-------------|--------------| | `listeDeProfils` | `4 columns x 1 row` | Grille 4 colonnes | | `temoignages` | `2 columns x N rows` | Grille 2 colonnes | | `domaineDeCompetence .competences` | `3 columns x 1 row` | 3 compétences en ligne | | `listeDesExperiencesEtApprentissages` | `accordeon, X rows` | Accordéon (fermé par défaut) | | `listeDeDetournementsVideo` | `X rows` | Liste verticale | | `listeDesPages` | `draw with page properties` | Rendu dynamique par zone | | `droitsAuteur` | `tooltip, droits d'auteur` | Popup au clic |

Usage CSS :

Identifie le container pour le mode lecture et le debug :

---

| Fichier | Usage | |---------|-------| | `app/content-styles.css` | Styles des types de contenu | | `app/globals.css` | Tokens CSS (variables) |

• Composants React (`components/*.tsx`)
• Utils (`utils/*.ts`)
• Pages (`app/(main)/*.tsx`)

---

Les info-bulles de la page Metrics apparaissaient sous d'autres éléments au lieu de flotter au-dessus.

Les tooltips étaient rendues DANS la carte parent, héritant de son contexte d'empilement (stacking context). Un `z-index` même très élevé ne peut pas sortir de ce contexte.

React Portal vers `document.body` :

• Une tooltip doit toujours utiliser un Portal
• Le mot "dessous" est ambigu (position Y vs z-index) — toujours préciser

---

Multiples corrections inefficaces car l'IA confondait :

• Position verticale (Y, "bottom")
• Z-index (couches d'empilement)

Le terme "dessous" a deux sens en CSS/UI.

Être explicite dans les prompts :

• ❌ "L'info bulle est sous les icônes"
• ✅ "L'info bulle est sous les icônes EN TERMES DE Z-INDEX (couches)"

Toujours préciser le concept technique quand un mot a plusieurs sens.

---

• Tests qui attendent `h1` alors que le composant utilise `h2`
• Chemins d'import obsolètes (`../../app/maintenance/page` vs `../../app/(main)/maintenance/page`)
• Props testées qui n'existent plus

Les tests n'avaient pas été mis à jour lors des refactorings précédents.

1. Chemins : Mettre à jour les imports après déplacement de fichiers
2. Assertions : Vérifier ce que le composant rend réellement, pas ce qu'il rendait avant
3. Props : Supprimer les tests de props obsolètes

Après un refactoring structurel, toujours lancer la suite de tests complète.

---

Le test E2E échouait car un e2eID généré par le système déterministe (plan du site) était identique à un e2eID du système séquentiel.

Les deux systèmes utilisaient la même plage de numéros (0-999).

2 plages réservées pour le système déterministe :

• `l600-l749` (150 numéros)
• `l800-l949` (150 numéros)

Le système séquentiel saute automatiquement ces plages.

Quand deux systèmes génèrent des identifiants, définir des plages disjointes.

---

"Complexité Cyclomatique : 5" affichée alors que la valeur n'est pas calculée.

Valeurs fictives hardcodées dans le code pour faire joli pendant le développement.

Remplacer par `"NC"` (Non Calculé) et masquer les cartes dont la valeur est `"NC"`.

Jamais de valeurs fictives en dur — utiliser un placeholder explicite ("NC", "N/A").

---

• v1 : Durées BDD et E2E identiques (une seule mesure)
• v2 : Durée BDD à zéro

Le fichier `data.json` de Playwright contenait les résultats combinés. La durée était lue depuis ce fichier au lieu d'être mesurée indépendamment.

Mesure séparée avec `Date.now()` :

Stockage dans `durations.json`, pas dans `data.json`.

Toujours mesurer les durées explicitement, ne pas les déduire de fichiers intermédiaires.

---

La page plan-du-site affichait un contenu vide sur Vercel mais fonctionnait en local.

1. Le fichier `_Pages-Liens-Et-Menus.json` n'était pas régénéré avant le build
2. Les pages n'avaient pas de propriété `zone` (filtrage échouait)

1. Génération automatique du plan du site dans le script de build
2. Assignation automatique des zones selon l'URL dans `detecterPages()`

Tout fichier généré doit être régénéré automatiquement lors du build.

---

Espace à droite dans la tooltip même après suppression de l'ascenseur.

Règles CSS résiduelles de l'ascenseur (`overflow-y: auto`, `max-height`).

Supprimer complètement les styles d'ascenseur :

Quand on supprime une fonctionnalité CSS, supprimer TOUTES les règles associées.

---

Vulnérabilité de sécurité permettant d'accéder à des fichiers hors du répertoire autorisé.

Concaténation directe du chemin utilisateur sans validation :

Validation avec `path.resolve()` :

Toujours valider les chemins avant d'accéder aux fichiers.

---

Le titre de la métrique apparaissait deux fois : dans le bloc bleu ET dans la tooltip.

Le composant `MetricTooltip` incluait un `<h4>` avec le titre.

Supprimer le titre de la tooltip — il est déjà visible juste en dessous sur le bloc bleu.

Éviter la redondance d'information dans l'UI.

---

Les citations dans les compétences n'affichaient plus l'auteur.

1. Le champ `auteur` n'était pas défini dans l'interface TypeScript
2. Le champ n'était pas copié lors de la résolution des références (bibliothèque)
3. La classe CSS utilisait `styles.competenceAuteur` au lieu de la classe globale

1. Ajouter `auteur?: string` à l'interface `Competence`
2. Copier `auteur: competence.auteur` dans `profilBuilder.ts`
3. Utiliser la classe globale `competenceAuteur`

Vérifier les 3 couches : interface TypeScript, logique de résolution, CSS.

---

Erreur "Failed to fetch" après refactorisation CSS.

Composants important des CSS modules vides (contenant seulement un commentaire de déplacement) sans les utiliser.

Supprimer tous les imports CSS modules non utilisés.

Après migration CSS, supprimer les imports obsolètes, pas seulement vider les fichiers.

---

Le scénario E2E visitait 63 pages alors que le site n'en a que 13.

L'algorithme glouton repassait plusieurs fois par les mêmes pages pour suivre différents liens.

Refactorisation : visiter chaque page une seule fois, marquer tous ses liens comme testés.

Un algorithme glouton naïf peut être très inefficace — optimiser dès que le résultat est anormal.

---

Tests Jest ne s'exécutent pas correctement.

Utilisation de `--testPathPattern` au lieu de `--testPathPatterns` (avec 's').

Vérifier la documentation pour les options CLI exactes.

---

Le board KanBan n'affichait que 2 colonnes (A faire, Fait) sur Vercel.

Le dossier `.cursor/agents` n'était pas poussé sur GitHub (`.gitignore`).

Créer `data/A propos/agents.json` comme source de vérité, synchronisé depuis `.cursor/agents` en dev.

Pour les données utilisées en production, avoir une source dans `data/` (pas dans `.cursor/`).

---

`npm run publie` échoue pendant les tests BDD puis E2E avec :

• `Port 3000 is in use by process X, using available port 3001 instead`
• `Unable to acquire lock at .next/dev/lock, is another instance of next dev running?`
• `Process from config.webServer was not able to start`

Un `next dev` tourne déjà (ex. dans un autre terminal). Playwright, avec `reuseExistingServer: true`, doit détecter que `http://localhost:3000` répond pour réutiliser ce serveur. Si la vérification échoue (timeout ou réponse lente), il lance un second `npm run dev`, qui tente le port 3001 puis échoue sur le lock partagé `.next/dev/lock`.

Dans `scripts/collect-metrics-simple.ts`, avant l’exécution des tests BDD, une attente explicite (`waitForServerReady`) vérifie que `http://localhost:3000` répond (2xx/3xx/4xx) pendant jusqu’à 15 s en local. Ainsi Playwright considère le serveur existant comme prêt et le réutilise au lieu d’en démarrer un second.

En pratique : soit ne pas lancer `npm run dev` avant `npm run publie` (Playwright démarrera le serveur), soit le lancer et attendre que Next affiche « Ready » avant de lancer `publie`.

En local, s’assurer que la sonde de réutilisation (URL prête) réussit avant que Playwright tente de lancer le webServer.

---

Ce catalogue sera enrichi au fil des problèmes rencontrés.

Efficace :

Dans 'index.json' remonte 'Développement informatique' sous 'Engager les équipes' 
et avant 'Interactions humaines'

Pourquoi : Action claire, fichier identifié, résultat attendu explicite.

Efficace :

Sur le metric 'Complexité cyclomatique' ajoute une info bulle avec ce tableau :
Complexité | Interprétation
1–10      | Excellente : Code simple...

Pourquoi : Format attendu montré, pas d'ambiguïté.

Efficace :

Les 5 blocs supérieurs de metrics ne sont pas responsives. 
Si SmartPhone, les empiler les uns sous les autres.

Pourquoi : Problème localisé, solution attendue claire.

Efficace :

Propose moi des options avec une lettre :
A) Corriger le test
B) Supprimer le test
C) Refactoriser le composant

Pourquoi : Réponse rapide avec "A", "B" ou "C".

---

Problématique :

L'info bulle est sous les icônes

Confusion : Position verticale (Y) ou z-index (couches) ?

Mieux :

L'info bulle est sous les icônes EN TERMES DE Z-INDEX (couches), 
pas en position verticale

Problématique :

Sur le metric 'Complexité cyclomatique' ajoute une info bulle

Confusion : Juste cette métrique ou les 19 ?

Mieux :

Sur TOUTES les 19 métriques de la page, ajoute une info bulle 
avec le contenu approprié

Problématique :

C'est illisible. Vas tu pouvoir corriger ?

Confusion : Qu'est-ce qui est lisible pour vous ?

Mieux :

Le fichier est illisible. Je veux un format chronologique :
- Une demande de ma part
- L'image illustrative juste au dessus ou en dessous
- Un résumé de ta réponse
Format factuel, pas de titres excessifs

Problématique :

Le fichier contient un titre H2. Les fichiers MD doivent commencer au H3.

Confusion : Remplacer tous les H2 ? Dans quel ordre ?

Mieux :

Corrige en remontant progressivement depuis le bas :
1. H6 → H5
2. H5 → H4
3. H4 → H3
4. Garde les 3 H2 originaux (lignes 231, 389, 471) en H3

Problématique :

Les images n'apparaissent pas

Manque : Le dossier images a été déplacé.

Mieux :

Les images n'apparaissent pas.
Contexte : Le dossier images a été déplacé de 
'data/A propos de ce site/images/' vers 'data/images/' à la racine.

---

Dans [fichier], [problème identifié].
[Explication de la cause si connue].
Solution attendue : [description claire].

Exemple :

Dans 'content-styles.css', les boutons débordent de leur conteneur.
Solution attendue : Ajouter max-width: 100% et box-sizing: border-box.

[Contexte : où, quand, pourquoi]
[Action souhaitée]
[Comportement attendu avec exemples]
[Contraintes ou exceptions]

Exemple :

Contexte : Page plan-du-site, besoin d'organiser visuellement.
Action : Grouper les pages par zones (HomePage, Profils, Autres, Footer).
Comportement :
- Ligne 1 : HomePage (centré)
- Ligne 2 : Profils (tous côte à côte)
- Ligne 3 gauche : Autres (colonne)
- Ligne 3 droite : Footer (colonne)
Contrainte : Boutons de 270x60px, centrés dans leur zone.

Symptôme : [ce qui se passe]
Attendu : [ce qui devrait se passer]
Contexte : [changements récents, fichiers concernés]
Pistes : [hypothèses si vous en avez]

---

Coûteux :

Prompt 1: "Corrige le problème"
IA: "Quel problème ?"
Prompt 2: "L'info bulle"
IA: "Quelle info bulle ?"
Prompt 3: "Celle de Complexité"

Économique :

Corrige l'info bulle "Complexité Cyclomatique" qui ne flotte pas au-dessus 
des cartes bleues (problème de z-index, pas de position verticale).

Coûteux : 5 prompts pour 5 corrections CSS indépendantes.

Économique :

5 corrections CSS à faire :
1. Bouton trop large → max-width: 270px
2. Texte sur 2 lignes → white-space: nowrap
3. Pas de rollover → :hover { background: var(--BleuClair) }
4. Titre en noir → color: var(--BleuFonce)
5. Marge droite → padding-right: 0

Coûteux : Répéter le contexte à chaque prompt.

Économique :

Contexte pour cette session : 
- On travaille sur la page Metrics
- Les tooltips utilisent React Portal
- Le thème des boutons est "Fond BleuFoncé / Texte blanc"
---
[Puis vos demandes sans répéter le contexte]

Coûteux : Redonner tout le contenu d'un fichier.

Économique :

Dans le fichier qu'on vient de créer (_site-identity.json), 
ajoute le champ "phone".

---

Peu efficace :

Tu fais n'importe quoi !

Efficace :

C'est quoi cette stratégie ? Si tu corriges d'abord les H2 en H3, 
comment vas-tu corriger les H3 en H4 ? Il faut commencer par le niveau le plus bas.

Peu efficace :

Tu aurais dû savoir que le hook pre-commit régénère automatiquement

Efficace :

Ce que tu viens de faire manuellement aurait dû être fait par le TI.
Va lire le fichier 'data/journaux/4. Architecture/Pre-commit hooks...' 
pour comprendre la stratégie automatique.

Quand : Après plusieurs corrections inefficaces.

Comment :

Prend de la hauteur. Oublie tout et repars des fondamentaux.
N'essaie pas d'appliquer un correctif mais fais une analyse 
plus systémique de la construction de la page et du CSS associé.

---

• Préciser plutôt que généraliser
• Montrer plutôt que décrire
• Exemple plutôt qu'abstraction

• Mentionner les changements récents
• Fournir les informations contextuelles
• Diriger vers la documentation si nécessaire

• Lister les actions
• Ordonner les étapes
• Définir les critères de succès

---

Ce guide est basé sur l'analyse de notre historique de collaboration, notamment la "bataille des tooltips" qui illustre parfaitement les patterns de friction et d'efficacité.

| Observation | Exemple | |-------------|---------| | Précision visuelle | "Les 3 compétences doivent être horizontalement sur PC, verticalement sur mobile" | | Détection des incohérences | Repérer les auteurs manquants, la marge résiduelle, les 4 tooltips oubliées | | Exigence qualité | Refus des valeurs hardcodées → "NC" plutôt que mentir | | Sensibilité UX | "L'info bulle ne tient pas dans l'écran", "Texte sur 2 lignes" |

| Observation | Exemple | |-------------|---------| | Structuration naturelle | US → BDD → TDD, sprints, Definition of Done | | Workflow clair | "GO US", "GO NEXT" — commandes simples et efficaces | | Traçabilité | Journal de bord, historique des décisions | | Comparaison scientifique | Deux projets parallèles pour évaluer les approches |

| Observation | Exemple | |-------------|---------| | Challenger sans casser | "Prends de la hauteur, repars des fondamentaux" | | Délégation claire | Agents spécialisés avec périmètres définis | | Feedback constructif | Expliquer pourquoi c'est faux, pas juste critiquer | | Savoir dire non | "Je refuse que l'UX-UI designer soit sollicité" après échecs répétés |

| Observation | Exemple | |-------------|---------| | Concepts maîtrisés | Architecture hexagonale, TDD, BDD, Clean Code | | Vision système | Comprendre que le problème vient des icônes, pas de la tooltip | | Pragmatisme technique | "C'est moche d'utiliser `any` alors que j'ai choisi TypeScript" |

---

| Pattern observé | Traduction technique | |-----------------|---------------------| | "flotter dessous" | z-index / stacking context | | "assensseur" | scrollbar / overflow | | "tetière" | header | | "rollover" | hover state |

Conséquence : Quelques allers-retours pour clarifier, mais le concept est toujours là.

| Pattern observé | Ce que ça signifie | |-----------------|-------------------| | Pas de proposition de code | Décrit le quoi, pas le comment | | Questions sur les mécanismes | "Comment est calculée la couverture ?" |

Conséquence : Besoin d'un binôme technique pour l'exécution.

| Pattern observé | Ce que ça signifie | |-----------------|-------------------| | Surprises sur Jest/Playwright | Options CLI, fichiers de config | | Dépendance à l'IA pour les commandes | `--testPathPatterns` vs `--testPathPattern` |

Conséquence : Pas un problème avec un dev ou une IA en support.

---

| Contexte | Contribution | |----------|-------------| | Projet sans PO clair | Structurer les US, définir les critères d'acceptation | | Équipe technique sans méthodo | Installer TDD/BDD, DoD, revues | | Produit avec dette UX | Identifier les incohérences, prioriser les corrections | | Transformation digitale | Faire le pont métier-tech, challenger les deux côtés | | Audit qualité | Évaluer un projet (comme l'audit 17 critères réalisé) |

| Contexte | Raison | |----------|--------| | Développeur au quotidien | Profil qui décrit, pas qui code | | Ops / DevOps | Configuration, infrastructure | | Architecte technique pur | Choix de frameworks, optimisation performance |

---

| Zone | Investissement | ROI | |------|----------------|-----| | Vocabulaire CSS | Faible (glossaire) | Moyen — moins d'allers-retours | | Bases Git avancées | Moyen | Élevé — autonomie sur les branches | | Lecture de code TypeScript | Moyen | Élevé — comprendre les PR |

| Zone | Investissement | ROI | |------|----------------|-----| | Outils IA (Cursor, Copilot) | Faible | Élevé — déjà très bien maîtrisé | | Frameworks BDD | Faible (déjà maîtrisé) | — | | Product Discovery | Moyen | Élevé — compléter le profil CPO |

Ne pas chercher à devenir développeur. La valeur est dans la capacité à :

1. Définir précisément ce qu'on veut
2. Structurer le travail méthodologiquement
3. Challenger avec bienveillance
4. Faire le pont entre vision et exécution

C'est un profil rare et recherché — beaucoup de devs, peu de gens qui savent définir clairement le besoin.

---

"Dans 'index.json' remonte 'Développement informatique' 
sous 'Engager les équipes' et avant 'Interactions humaines'"

→ Action claire, fichier identifié, résultat attendu explicite.

"L'info bulle est sous les icônes"

→ Ambiguïté : position verticale ou z-index ?

| Avant | Après | |-------|-------| | "L'info bulle est sous les icônes" | "L'info bulle est sous les icônes EN TERMES DE Z-INDEX (couches)" | | "C'est illisible" | "Format attendu : chronologique, une demande → une réponse" | | "Corrige les H2" | "Corrige en remontant depuis le bas : H6→H5, H5→H4..." |

---

Document généré le 2 février 2026 à partir de l'analyse des échanges projet.

Ce site fonctionne comme un CMS : chaque page est construite à partir d’une liste d’éléments de contenu (propriété `contenu` dans les JSON de page). Chaque élément a un typeDeContenu — identifiant métier en camelCase, propriété `type` dans le JSON, type TypeScript `TypeDeContenu` dans `pageReader.ts`. Le rendu et le style s’appuient sur des containers (suffixe `.cont`, classe CSS `typeContenu-cont`). Source unique des types : `utils/vitrine/pageReader.ts` (`TypeDeContenu`). Ordre d’affichage : selon l’énumération des noms canoniques dans `constants/canonicalSpec.ts`.

Les typeDeContenu détaillés dans les sections 2 à 5 ne sont pas redécrits ici (voir les sections indiquées). Les autres sont définis dans le tableau ci‑dessous.

| typeDeContenu | Container (.cont) | Détail | |---------------|-------------------|--------| | titreDePage | — | Titre principal de la page. JSON. | | listeDesPages | listeDesPages.cont | Affiche le plan du site (liens par zone). Données injectées par le script du plan. plan-du-site.json, ListeDesPages, canonicalSpec. | | hero | hero.cont | Voir section 2 (Hero / Profils professionnels). | | listeDeProfils | listeDeProfils.cont | Voir section 2. | | profil | profil.cont | Voir section 2. | | titre | — | Titre de section (texte). JSON, rendu titre. | | video | — | Vidéo YouTube (url, lancement auto). JSON, pageReader. | | listeDeTemoignages | listeDeTemoignages.cont | Voir section 4 (Témoignages). | | temoignage | temoignage.cont | Voir section 4. | | domaineDeCompetence | domaineDeCompetence.cont | Voir section 3 (Domaines de compétence et expériences). | | competence | competence.cont | Voir section 3. | | listeDesExperiencesEtApprentissage | listeDesExperiencesEtApprentissages.cont | Voir section 3. | | experienceEtApprentissage | experienceEtApprentissage.cont | Voir section 3. | | texteLarge | — | Paragraphe de texte large. JSON. | | callToAction | — | Bouton d’action principal (texte, action). JSON, hero, pages. | | groupeDeBoutons | groupeDeBoutons.cont | Groupe de boutons (taille petite/grande). JSON, canonicalSpec. | | bouton | bouton.cont | Item d’un groupe de boutons (icône, texte, url/command). groupeDeBoutons.boutons, canonicalSpec. | | listeDeDetournementsVideo | listeDeDetournementsVideo.cont | Voir section 5 (Détournements vidéo). | | detournementVideo | detournementVideo.cont | Voir section 5. |

---

| Terme | Définition | Où | |-------|------------|-----| | hero | Bannière d’accueil (typeDeContenu). Titre, sous-titre, description, CTA, vidéo, lien « En savoir plus ». | Page d’accueil, canonicalSpec | | profil | Profil métier (CPO, COO, Agile, CTO). typeDeContenu (item dans hero ou listeDeProfils) ; aussi catégorie cliquable dans les liens (`Profil` en PascalCase). | JSON (type `profil`), `pageReader`, `planDuSiteTypes` (TypeElementCliquable) | | listeDeProfils | typeDeContenu : liste de profils (cartes). Données : tableau `profils`. Container `listeDeProfils.cont`. | `mes-profils.json`, `pageReader`, composant ListeDeProfils, canonicalSpec | | profil (container) | Pour chaque carte profil, container profil.cont (classe `profil-cont`). Rester sur container et le suffixe `.cont`. | `canonicalSpec.ts`, ProfilContainer, CSS | | slug | Identifiant court d’un profil (ex. `cpo`, `coo`, `agile`, `cto`). | `mes-profils.json` (profil.slug) |

---

| Terme | Définition | Où | |-------|------------|-----| | domaineDeCompetence | typeDeContenu : domaine avec titre, texte, liste de compétences, expériences. Container `domaineDeCompetence.cont`. | Profils (profil-*.json), profilBuilder, canonicalSpec | | competence | typeDeContenu : carte compétence dans un domaine (titre, description, bouton). En liens du plan : Competence (PascalCase). | domaineDeCompetence.items, canonicalSpec, planDuSiteTypes | | listeDesExperiencesEtApprentissage | typeDeContenu : conteneur logique pour la liste d’expériences d’un domaine. | pageReader (lecture), canonicalSpec | | experienceEtApprentissage | typeDeContenu : item expérience dans un domaine (categorie, description, periode). | domaineDeCompetence.experiences, canonicalSpec |

---

| Terme | Définition | Où | |-------|------------|-----| | listeDeTemoignages | typeDeContenu : liste de témoignages. Container `listeDeTemoignages.cont`. | JSON, canonicalSpec | | temoignage | typeDeContenu : item témoignage (nom, fonction, photo, texte). Container `temoignage.cont`. | listeDeTemoignages.items, JSON, pageReader |

---

| Terme | Définition | Où | |-------|------------|-----| | listeDeDetournementsVideo | typeDeContenu : liste de détournements vidéo. Container `listeDeDetournementsVideo.cont`. | JSON, canonicalSpec | | detournementVideo | typeDeContenu : item (vidéo détournée + vidéo originale, titre, pitch, date). Container `detournementVideo.cont`. | listeDeDetournementsVideo.items, canonicalSpec | | detournement | Sans accent : URLs, chemins, clés techniques (ex. `/detournement-video`, types `detournementVideo`, `listeDeDetournementsVideo`). | URLs, JSON, `pageReader` | | détournement | Avec accent : libellés affichés à l’utilisateur (titres, descriptions). | Textes des pages, métadonnées affichées |

---

Concept général (données réutilisables : compétences, domaines, témoignages, etc.), distinct des typeDeContenu.

| Terme | Définition | Où | |-------|------------|-----| | bibliotheque | Sans accent : noms de fichiers, chemins, identifiants techniques (dossier `data/bibliotheque/`, types, imports). | `bibliothequeReader`, chemins, types | | bibliothèque | Avec accent : acceptable en français dans la documentation et les libellés affichés. | Descriptions OpenAPI, textes utilisateur |

---

Règle DOM/CSS : à chaque typeDeContenu correspond un container avec le suffixe `.cont` (nom canonique) ; en classe CSS : `typeContenu-cont`. Ne pas utiliser le vocable « bloc » : rester sur container et typeDeContenu. Liste des typeDeContenu en section 1 ; détails dans les sections 2 à 5.

| Terme | Définition | Où | |-------|------------|-----| | contenu | Liste ordonnée d’éléments de la page. Chaque élément a une propriété `type` (son typeDeContenu). | Propriété `contenu` des JSON de page, `pageReader.ts` | | content | Réservé aux usages techniques (ex. segments markdown, champs internes). À ne pas utiliser pour la liste d’éléments de page. | `markdownInlineParserPure`, `aboutSiteReader` (champs internes) | | typeDeContenu | Identifiant métier d’un élément de contenu (camelCase). Propriété `type` dans le JSON ; type TypeScript `TypeDeContenu` dans `pageReader.ts`. À ne pas confondre avec le mot-clé `type` de TypeScript. | Tous les JSON de page (`element.type`), `TypeDeContenu` dans `pageReader.ts` | | typeElement | Catégorie cliquable d’un lien du plan, PascalCase (ex. `Competence`, `Profil`, `LienPage`). Distinct du typeDeContenu (contenu de page). | Liens du plan, `TypeElementCliquable` dans `planDuSiteTypes.ts` |

---

• A — Concept métier : en doc, discussions et libellés utilisateur, on écrit en français, avec espaces et accents (ex. compétence, détournement, bibliothèque).
• B — Syntaxe dans le code : selon le type d’élément, contraintes techniques à respecter.

| Type d’élément | Règle B | Exemples | |----------------|---------|----------| | Fichier / dossier | Pas d’accent, pas d’espace | `bibliotheque/`, `planDuSiteGenerator.ts` | | Clé JSON métier | camelCase, pas d’accent | `type`, `listeDeProfils`, `domaineDeCompetence` | | typeDeContenu (contenu de page) | camelCase | `domaineDeCompetence`, `listeDeTemoignages` | | typeElement (liens du plan) | PascalCase | `Competence`, `Profil`, `LienPage` | | Classe CSS | Pas d’accent, convention projet | `listeDeProfils-cont`, `profil-cont` | | URL / route | Pas d’accent | `/detournement-video`, `/mes-profils` |

Libellés affichés à l’utilisateur (titres, descriptions dans les JSON) : français avec accents (A). Identifiants techniques (clés, chemins, types) : pas d’accent (B).

---

Trois termes pour éviter toute confusion.

| Terme | Usage | Propriétés / où | Règle | |-------|--------|-----------------|--------| | titre | Libellé affiché pour une page, un élément de contenu ou une carte (section, domaine, profil, témoignage, etc.). Pas pour le texte d’un lien. | `titre` dans les JSON de page (PlanPage, éléments), `profil.titre`, `domaineDeCompetence.titre`, hero.titre, etc. Affiché dans le header (titre de page), dans les cartes, sections. | Toujours titre (propriété `titre`) pour tout libellé de page ou d’élément ; jamais `titre` pour un lien cliquable (voir label). | | label | Texte cliquable d’un lien ou d’une entrée de menu. | `label` dans les liens du plan (_Pages-Liens-Et-Menus.json), `label` dans _Menus-header.json (entrées de menu). | Réservé aux liens et menus ; ne pas exposer un libellé de lien sous la propriété `titre`. | | title | Technique SEO uniquement : balise `<title>`, partage réseaux. | `metadata.title` dans les JSON de page. En doc : dire « titre SEO » ou « metadata.title ». | Ne jamais utiliser « title » pour le titre affiché à l’utilisateur ; on dit titre. |

---

| Terme | Définition | Où | |-------|------------|-----| | url | Lien pouvant pointer vers l’extérieur du site (https, mailto, etc.) ou être une adresse générique. | Boutons, liens externes, champs de type « lien » | | route | Chemin interne au site (ex. `/`, `/mes-profils`, `/profil/cpo`). Un seul terme pour tout lien interne. | Plan du site (pages, liens), `mes-profils.json` (profil.route), `_Menus-header.json` (entrée.pageUrl) | | titre | Voir section 9. Libellé affiché pour une page ou un élément (pas pour un lien). | Propriété `titre` des pages et éléments | | metadata.title | Voir section 9. Titre SEO (technique). | Fichiers JSON de page : `metadata.title` | | label | Voir section 9. Texte cliquable d’un lien ou d’une entrée de menu. | Liens du plan (`label`), _Menus-header.json (`label`) | | zone | Zone d’affichage d’une page dans le plan du site : `HomePage`, `Profils`, `Autres`, `Footer`, `Masqué`. | _Pages-Liens-Et-Menus.json, type `PlanPage.zone` | | dessiner | Indique si la page doit apparaître dans le plan affiché : "Oui" ou "Non" (majuscule). | _Pages-Liens-Et-Menus.json, type `PlanPage.dessiner` |

---

| Terme | Définition | Où | |-------|------------|-----| | menu header / header | Menu principal du site (navigation en haut). | Layout, `headerMenuReader`, _Menus-header.json (source éditable) | | menus | Nom de la section JSON dans _Pages-Liens-Et-Menus.json qui contient les entrées du menu (fusion depuis _Menus-header.json). | _Pages-Liens-Et-Menus.json (clé `menus`) | | entrée | Une ligne du menu : objet avec `id`, `pageUrl`, `label`, optionnellement `sousmenuPageUrls`. | _Menus-header.json, _Pages-Liens-Et-Menus.json |

---

| Terme | Définition | Où | |-------|------------|-----| | \_Pages-Liens-Et-Menus.json | Fichier JSON regroupant la liste des pages, des liens entre pages et la section menus. Source de vérité pour le plan du site et le menu header. | `data/`, lu par le générateur de plan, `headerMenuReader`, `pageReader` | | plan du site / planDuSite | Données (pages + liens) issues de _Pages-Liens-Et-Menus.json. À utiliser exclusivement en français en doc et en camelCase en code (planDuSite). Ne pas utiliser « site map » ni « sitemap » pour ces données. | Types `PlanPage`, `PlanLien`, `PlanSite` dans `utils/shared/planDuSiteTypes.ts` | | sitemap (exception) | Uniquement l’artefact SEO sitemap.xml et la route Next.js qui le génère (`app/sitemap.ts`). À ne pas confondre avec le plan du site. | `app/sitemap.ts` génère sitemap.xml à partir du plan du site | | page (plan) | Objet décrivant une page du site : `url` (contient une route), `titre`, `zone`, `dessiner`, `x`, `y`, optionnellement `e2eID`. | _Pages-Liens-Et-Menus.json, interface `PlanPage` | | lien (plan) | Objet décrivant un lien cliquable entre deux pages : `source`, `destination` (des routes), `label`, `e2eID`, `typeElement`. | _Pages-Liens-Et-Menus.json, interface `PlanLien` |

---

| Terme | Définition | Où | |-------|------------|-----| | e2eID | Identifiant unique pour les tests E2E (camelCase). Un élément interactif = un e2eID. Une page du plan = au plus un e2eID. | Éléments de contenu (video, callToAction, etc.), liens du plan, pages du plan, règle `.cursor/rules/e2eid-convention.mdc` |

---

| Terme | Définition | Où | |-------|------------|-----| | A propos | Contexte limité regroupant le contenu éditorial du site (documentation, sprints, configuration, métriques). En doc : « A propos » (avec espace). En code : a-propos (route `/a-propos`). | `constants/routes.ts`, `app/(main)/a-propos/` | | dossier à propos | Vocable unifié pour l’arbre de dossiers « A propos ». Deux usages : (1) Racine = dossier racine, chemin `data/<A_PROPOS_DATA_DIR>` (ex. `data/A propos`), contient `menu.json`, `agents.json`, sous-dossiers (Sprints, Documentation technique, etc.). (2) Chemin = chemin relatif vers la racine ou un sous-dossier (ex. `data/A propos/Documentation technique`) ; une entrée de menu de type Path a Parametre = ce chemin ; la page `/a-propos/[dossier]` affiche son contenu. | Racine : `aProposReader.ts`, `menuReader.ts`, `sprintBoardReader.ts`. Chemin : `menu.json` (Parametre), `readPathContentAtRoot`, `AProposDossierPage` | | A_PROPOS_DATA_DIR | Constante donnant le nom du segment du chemin de la racine du dossier à propos (valeur `'A propos'`). Chemin racine = `data/` + A_PROPOS_DATA_DIR. Utilisée partout où on construit un chemin vers la racine ou un sous-dossier. | `constants/routes.ts`, `constants/aProposPath.ts`, `aProposReader.ts`, `menuReader.ts`, `sprintBoardReader.ts`, tests |

Hiérarchie markdown lue par `aProposReader` : dossier → chapitre, fichier MD → section, titres ### / #### / ##### → partie, sous-partie, bloc.

| Terme | Définition | Où | |-------|------------|-----| | chapitre | Dossier dans un Path ; contient des sections (fichiers .md). En affichage : titre H1, liste des sections ou accordéon. | `Chapitre`, `DossierRacine`, `aProposReader.ts` | | section | Fichier markdown dans un chapitre ; contient des parties (###). Propriétés : `nom` (sans .md), `contenu`, `parties`, `niveauBase`. | `Section`, `SectionContent`, `aProposReader.ts` | | partie | Bloc de contenu délimité par un titre ### dans le MD. Contient des sous-parties (####) et du contenu parsé (`contenuParse`). | `Partie`, `aProposReader.ts` | | sous-partie | Bloc délimité par ####. Contient des blocs (#####) et du contenu parsé. | `SousPartie`, `aProposReader.ts` | | bloc | Bloc délimité par ##### (ex. « Prompt », « Résultat technique »). Contient `contenu`, `contenuParse`, optionnellement `typeDeContenu`. | `Bloc`, `aProposReader.ts` | | PathContentAtRoot | Contenu à la racine d’un Path : `fichiers` (Section[]) et `dossiers` (DossierRacine[]). Fichiers MD = H1 directs ; dossiers = H1 avec accordéon (sauf affichage direct si un seul fichier). | `readPathContentAtRoot`, `AProposContent`, `aProposReader.ts` | | DossierRacine | Dossier à la racine d’un Path : `nom`, `path` (chemin pour déplier), optionnellement `chapitre` (si un seul fichier MD = affichage direct sans accordéon). | `PathContentAtRoot.dossiers`, `aProposReader.ts` | | AProposStructure | Structure complète « A propos » pour un chemin donné : `chapitres` (tableau de Chapitre). Utilisée quand on lit un dossier entier (ex. pour export ou tableau de bord). | `AProposStructure`, `aProposReader.ts`, `AProposContent` | | ContenuElement | Élément parsé dans un bloc (paragraphe, liste, code, image). Partagé avec le domaine Vitrine (rendu markdown). Propriété contenu (pas `content`) pour le texte. | `aProposReader.ts`, `AProposContentRenderer`, section 7 | | accordéon | Affichage des dossiers à la racine d’un Path : un clic déplie/replie le contenu du dossier. Si le dossier ne contient qu’un seul fichier MD, affichage direct sans accordéon (US-10.3). | Composants A propos, `data-layout="accordeon"` (DOM), doc technique |

Menu latéral de la zone « A propos » : entrées lues depuis `data/A propos/menu.json`, triées par Numéro.

| Terme | Définition | Où | |-------|------------|-----| | LigneDeMenu | Une entrée du menu A propos : `Titre`, `Numéro`, `Type` (Path ou container), `Parametre`, optionnellement `e2eID`. | `menu.json`, `menuReader.ts`, type `LigneDeMenu` | | Titre (menu) | Libellé affiché pour l’entrée de menu (ex. « A propos du projet », « Sprint en cours »). Propriété Titre (PascalCase) dans le JSON. | `menu.json`, bande horizontale A propos | | Type (menu) | Path = lien vers un dossier (Parametre = chemin relatif) ; container = vue spéciale (ex. `sprintEnCours`, `metrics`, `openapi`, `charte`). | `menu.json`, `LigneDeMenu.Type` | | Parametre | Valeur associée à l’entrée : pour Type=Path, chemin relatif (ex. `data/A propos/Documentation technique`) ; pour Type=container, identifiant (ex. `sprintEnCours`, `metrics`). | `menu.json`, passé à la page ou au layout pour afficher le bon contenu | | menu.json | Fichier source du menu A propos. Tableau d’objets (Titre, Numéro, Type, Parametre, e2eID). Tri par Numéro à la lecture. | `data/A propos/menu.json`, `readMenu()` |

Contenu markdown hors « A propos » : fichiers journaux datés dans JOURNAL_DE_BORD.

| Terme | Définition | Où | |-------|------------|-----| | journal de bord | Ensemble des fichiers markdown du JOURNAL_DE_BORD : nommage `YYYY-MM-DD.md`, tri par date. Chaque fichier = JournalFile (filename, date, title, contenu). | `journalReader.ts`, dossier `JOURNAL_DE_BORD` (racine projet) | | JournalFile | Fichier journal lu : `filename`, `date` (YYYY-MM-DD), `title` (première ligne ou extrait), `contenu` (brut MD). | `readJournalFiles()`, `journalReader.ts`, composants liste journal | | JOURNAL_DE_BORD | Dossier racine (cwd) contenant les journaux. Ne pas confondre avec `data/A propos` (sprints, doc). | `journalReader.ts` |

Suivi Agile : sprint en cours, post-its US, colonnes (A faire, agents, Fait), détail US en modal.

| Terme | Définition | Où | |-------|------------|-----| | sprint | Période de développement ; dossier sous `data/A propos/Sprints` (ex. `2026-02-04 - Amélioration du message délivré`). Contient des fichiers US (`US-X.Y - Titre.md`), Sprint Goal (`00 - Sprint goal et contexte.md`), et optionnellement US en cours (`US en cours.md`). | `sprintBoardReader.ts`, `Sprints/` | | sprint en cours | Dernier sprint connu contenant au moins une US. Détermine le tableau affiché (menu « Sprint en cours »). | `getSprintFolderContainingUs`, `readSprintBoardData` | | Sprint Goal | Texte lu après la ligne `# Sprint Goal` dans `00 - Sprint goal et contexte.md` du dossier sprint. | `readSprintGoal`, `DonneesTableauKanban.goal` | | US en cours | Fichier métadonnée `US en cours.md` à la racine de `data/A propos/Sprints` : indique l’US et l’étape courantes (ex. « US-8.6 - TDD-front-end »). Non affiché dans la liste des documents A propos. | `UsEnCours`, `readUsEnCours`, `sprintBoardReader.ts` | | tableau Kanban / DonneesTableauKanban | Données du tableau Kanban : `goal`, `columns` (A faire, colonnes agent, Fait), `cards` (PostItUS[]). | `sprintBoardReader.ts`, `readSprintBoardData`, composant SprintBoardKanban | | Post-it d'US / PostItUS | Carte US sur le tableau : `id`, `titre`, `filename`, `state` (a_faire, en_cours, fait), `agentColumn`, `rotation`, `enRevue`. | `PostItUS`, `ColonneTableauKanban`, `sprintBoardReader.ts` | | Colonne de tableau Kanban / ColonneTableauKanban | Colonne du tableau : `id`, `label`, `type` (a_faire, agent, fait), `count`, optionnellement `wipLimit`. | `DonneesTableauKanban.columns` | | agents | Colonnes « agent » du tableau (ex. US, BDD, TDD-back-end). Liste lue depuis `data/A propos/agents.json` ou `.cursor/agents` (fichiers `N. Nom.md`). | `readAgentsFromCursorAgents`, `readAgentsFromConfig`, `sprintBoardReader.ts` | | contenu d'une US / ContenuUS | Contenu complet d’une US pour la modal détail : `id`, `titre`, `contenu` (markdown brut du fichier .md). | `readUsContent`, `UsDetailModal`, API `/api/sprint-board/us/[usId]` |

---

| Terme | Définition | Où | |-------|------------|-----| | maintenance / page maintenance | Route /maintenance. Accessible uniquement en mode développement ou lorsque l’utilisateur est authentifié (EditingContext). Sinon redirection vers `/`. Contenu : message easter egg et un CallToAction (bouton « Faisons connaissance... »). | `app/(main)/maintenance/page.tsx`, `ROUTES.MAINTENANCE` | | easter egg | Contenu caché (Bravo, message ludique, œuf) affiché sur la page maintenance. Utilise le même composant CallToAction que la Vitrine (type `callToAction`). | `maintenance/page.tsx`, styles `maintenance.module.css` |

---

1. Tester les fonctions non couvertes : `getLiensAParcourirInitial`, `getPagesAccessiblesDepuis`, `retirerLienUtilise`, `pageAccueil`.
2. Couvrir les branches `plan?.liens ?? []`, `(liens ?? []).filter`, et les cas limites de `retirerLienUtilise`.
3. Gain estimé : ~14 branches.

1. planDuSiteTypes.ts

1. Ouvrir `tests/unit/e2eIdGenerator.test.ts` et le rapport HTML de couverture (`coverage/index.html`) pour ce fichier.
2. Ajouter des cas pour les branches non couvertes (chemins alternatifs, valeurs nulles/undefined, cas limites).
3. Gain estimé : 15–25 branches.

1. e2eIdGenerator.ts

1. Ajouter des tests pour les branches autour des lignes 102–104 (états vides, métriques manquantes, formats de durée).
2. Gain estimé : ~10–15 branches.

1. MetricsCompact.tsx

1. Créer `tests/unit/e2eIdMapping.test.ts` (ou équivalent) et couvrir les chemins principaux et les cas d’erreur / limites.
2. Gain estimé : 20–35 branches.

1. e2eIdMapping.ts

1. Vérifier où il est utilisé (API, build, etc.). Si couvert par les tests d’intégration, envisager des tests unitaires ciblés.
2. Gain estimé : jusqu’à 44 branches si tout est couvert.

1. apiTreeBuilder.ts

1. Consulter le rapport HTML `coverage/index.html` pour voir les branches exactes (lignes jaunes/orange) et ajouter un ou deux tests ciblés par fichier.

1. ListeDesPages.tsx (47 branches, 33 couvertes), MenuAPropos.tsx (34, 24), PageContentRenderer.tsx (37, 25), HeroSection.tsx (20, 13), MarkdownRenderer.tsx (16, 12), etc.

---

1.1 Règles A (concept métier) et B (syntaxe code)

• Ajouter au dictionnaire (ou à un fichier « Conventions A/B » référencé) :

• A : concept métier = français, espaces, accents autorisés (doc, libellés, discussions).
• B : tableau par type d’élément :
• Fichier / dossier : pas d’accent, pas d’espace (ex. `bibliotheque`, `planDuSiteGenerator.ts`).
• Clé JSON métier : camelCase, pas d’accent (ex. `type`, `listeDeProfils`, `domaineDeCompetence`).
• Type TS (typeDeContenu, typeElement) : camelCase / PascalCase selon usage existant.
• Classe CSS : pas d’accent, convention du projet (ex. `listeDeProfils-cont`).
• URL / route : pas d’accent (ex. `/detournement-video`).

• Préciser pour typeElement (liens du plan) : PascalCase volontaire (Competence, Profil, LienPage) vs typeDeContenu en camelCase.

1.2 titre

• Dans le dictionnaire, une entrée dédiée titre qui liste :

• Tous les cas d’usage (titre de page, titre d’élément de contenu, titre de section, titre de carte).
• Les propriétés concernées : `titre` (JSON de page), `metadata.title` (SEO), affichage header.
• La règle : « titre » = libellé affiché pour une page ou un élément ; ne pas utiliser « titre » pour le texte d’un lien (voir label).

1.3 label

• Entrée label : réservé au texte cliquable (lien du plan, entrée de menu). Propriétés : `label` (plan, _Menus-header.json). Règle : aucun libellé de lien ou de menu ne doit être exposé sous le nom de propriété `titre` dans les données.

1.4 title

• Entrée title : réservé au technique SEO (`metadata.title`, balise `<title>`, partage). Règle : en doc, dire « titre SEO » ou « metadata.title » ; ne jamais utiliser « title » pour le titre affiché (on dit titre).

---

• Objectif : une page = un seul e2eID. Supprimer e2eIDs partout.
• État actuel : `PlanPage` a `e2eID?: string` et `e2eIDs?: string[]`. _Pages-Liens-Et-Menus.json peut contenir `e2eIDs` (tableau). plan-du-site.json / `PagePlanDuSite` utilisent `e2eID` (singulier).
• Implémentation :

• Retirer `e2eIDs` du type `PlanPage` dans `utils/shared/planDuSiteTypes.ts`.
• Migrer les données : pour toute page ayant `e2eIDs`, choisir une règle (ex. prendre le premier élément du tableau comme `e2eID`, ou laisser vide si plusieurs étaient utilisés pour autre chose) ; supprimer la clé `e2eIDs` des JSON.
• Mettre à jour `planDuSiteGenerator.ts` (ne plus lire ni écrire `e2eIDs`).
• Mettre à jour les tests (BDD, intégration) et les steps qui mentionnent `e2eIDs`.
• Documenter dans le dictionnaire : une page du plan a au plus un e2eID.

---

• Objectif : tous les contenus (JSON ou MD) = contenu (terme métier). content réservé au strict technique (champs internes TS, API du langage).
• Actions :

• Audit : repérer tous les usages de `content` dans les types, JSON et MD qui portent du contenu métier (données de page, blocs markdown métier, etc.).
• Renommer en contenu (ou terme français adapté) partout où c’est du contenu métier (y compris dans les structures issues de MD).
• Garder content uniquement là où c’est technique (ex. segment de markdown parsé, propriété interne d’un type TS sans sémantique métier).
• Documenter dans le dictionnaire : « contenu = tout contenu métier (JSON, MD) ; content = technique uniquement (parsers, champs internes) ».

---

• Après phase 1, vérifier :

• Libellés affichés (titres, descriptions) : bien en français avec accents quand c’est pour l’utilisateur.
• Identifiants techniques (clés JSON, routes, noms de fichiers, classes CSS) : pas d’accent, conformes à B.

• Corriger les écarts (ex. libellé JSON « detournement » affiché à l’utilisateur → « détournement » si c’est du métier affiché).

---