# Spec — Pipeline de génération PDF des cartes action Uluana

## Contexte
Ce pipeline transforme un export JSON de carte action (structure `detail` + `guide` + `examples`)
en fiche-guide PDF autonome, pensée pour un artisan qui doit exécuter l'action de A à Z.
Validé visuellement sur la carte C-087 ("Mettre en place une charte graphique simple").

## Fichiers du pipeline (à réutiliser tels quels, ne pas dupliquer la logique)
- `template.html` — template Jinja2, structure figée ci-dessous
- `card-guide.css` — feuille de style **unique**, classes génériques réutilisables sur toutes les cartes
- `categories.json` — mapping `category_id` → libellé humain (ex. CAT-05 → "Image de marque")
- `generate_card_pdf.py` — génère un PDF à partir d'un export JSON + un fichier d'enrichissement optionnel

## Règle CSS (non négociable)
- Une seule feuille de style pour toutes les fiches-cartes : `card-guide.css`.
- Les classes doivent être réutilisées entre cartes et entre blocs si possible. Non-redondance prioritaire :
  jamais de style dupliqué ou de CSS inline propre à une carte particulière.
- Toute nouvelle carte doit passer par les classes existantes (`.step`, `.callout`, `.charter-example`,
  `.metric`...). Une nouvelle classe ne se crée que si aucune existante ne convient — et dans ce cas,
  elle doit être générique (réutilisable par d'autres cartes), jamais nommée d'après la carte en cours.
- Couleurs/typo : reprendre les variables de marque (`--green`, `--amber`, `--red-*`, `--display`,
  `--body`...) déjà définies en haut de `card-guide.css` — ne jamais coder une couleur en dur ailleurs.

## Structure du document (ordre figé, validé par Mr Fauquant)
1. **En-tête** — titre, libellé catégorie (jamais l'ID brut), difficulté, tags, prérequis
2. **Pourquoi cette action** — intro contextuelle
3. **Méthode étape par étape** — pour chaque étape :
   - titre + contenu pédagogique (`detail.sections[method].steps`)
   - la question de cadrage correspondante (même rang), intégrée **dans** l'étape, jamais en section à part
   - un bloc "comment faire concrètement" (`comment_faire_par_etape`, cf. Enrichissement)
4. **Exemples concrets** — 2-3 exemples réels/illustratifs adaptés au thème de la carte
   (`exemples_concrets`, cf. Enrichissement). Jamais une simple phrase-anecdote isolée dans une étape :
   ce bloc doit être visuel et autonome (ex. palettes de couleurs avec pastilles hex si carte visuelle,
   sinon adapter le format au type de contenu de la carte — texte structuré, mini-tableau, etc.)
5. **Premier pas** — action minimale immédiate, temps estimé, livrable attendu
6. **Ce qu'il faut savoir** — conseils Uluana (`tips`) + pièges à éviter (`warnings`)
7. **Preuve sociale** — témoignage artisan (`examples[0]`)
8. **Mesurer sa réussite** — indicateurs (`guide.mesure.indicateurs`)
9. **Suite du parcours** — cartes avant/après (`liens_cards`)

Ne pas réordonner, fusionner ou scinder ces blocs sans validation explicite de Mr Fauquant.

## Enrichissement (obligatoire si absent du JSON source)
Deux champs n'existent pas encore dans le schéma catalogue et doivent être générés :
- `comment_faire_par_etape` : `{ "<numero_etape>": ["conseil pratique 1", "conseil pratique 2"] }`
  → outils, méthodes concrètes, sites/ressources nommés. 2 items par étape, pas plus.
- `exemples_concrets` : liste de 2-3 exemples adaptés au thème de la carte.

**Règle stricte : ne jamais écrire cet enrichissement dans les fichiers JSON sources.**
Toujours produire un fichier séparé `enrichissement_<card_id>.json` (ou un fichier groupé
`enrichissement_cartes.json` avec le `card_id` en clé si traitement en lot), pour validation
par Mr Fauquant avant tout import en base.

## Traitement en lot
1. Prendre l'export JSON (une ou plusieurs cartes)
2. Pour chaque carte : vérifier si `comment_faire_par_etape` / `exemples_concrets` existent déjà
   (dans un enrichissement fourni) — sinon les rédiger
3. Générer le PDF via `generate_card_pdf.py <export.json> <output.pdf> <card_id> --enrich <enrichissement.json>`
4. **Ne pas traiter les 124 cartes d'un coup.** Traiter un échantillon de 5-10 cartes variées
   (différents nombres d'étapes, avec/sans exemple, différentes catégories), les présenter à
   Mr Fauquant pour validation visuelle, puis seulement passer au lot complet une fois l'échantillon validé.
5. Si une carte a une structure inhabituelle (0 étape, 5+ étapes, pas d'exemple, pas de warning...),
   signaler le cas plutôt que de forcer le template — certains blocs sont conditionnels
   (`{% if %}` dans le template) mais un cas jamais vu doit être remonté.

## Rappel schéma cible (si import SQL prévu)
`comment_faire_par_etape` et `exemples_concrets` peuvent être stockés en colonnes JSON MySQL
sur la table carte/guide existante — pas de nouvelle table nécessaire.