docs: add comprehensive project documentation (DOCUMENTATION.md)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-18 03:02:57 +02:00 · 2026-05-18 03:02:57 +02:00 · 3c97378c46
commit 3c97378c46
parent 20c8280e4a
1 changed files with 256 additions and 0 deletions
--- a/DOCUMENTATION.md
+++ b/DOCUMENTATION.md
@ -0,0 +1,256 @@
+# CV Web — Stéphane Liabeuf
+
+> CV en ligne auto-hébergé, multi-versions et multi-thèmes, déployé automatiquement via Forgejo + Coolify.
+
+---
+
+## Présentation du projet
+
+Ce projet est un **CV interactif 100 % auto-hébergé**, conçu pour être présenté à des interlocuteurs différents (recruteurs, clients, DSI, équipes UX) avec une version adaptée à chaque cible, le tout à partir d'un seul fichier HTML et de fichiers de données JSON interchangeables.
+
+Le site est accessible à l'adresse : **https://cv.stephaneliabeuf.fr**
+
+---
+
+## Architecture technique
+
+### Principe fondamental
+
+L'ensemble du rendu est assuré par un **seul fichier `index.html`** qui :
+
+1. Lit le paramètre d'URL `?cv=` pour sélectionner le fichier JSON à charger
+2. Fetche le JSON correspondant via `fetch()`
+3. Injecte dynamiquement tout le contenu dans le DOM (hero, nav, expériences, compétences, secteurs, formation, footer)
+4. Applique le thème visuel choisi (stocké en `localStorage`)
+
+Aucun framework, aucun bundler, aucune dépendance serveur — le site est du **HTML/CSS/JS vanilla** servi par Nginx.
+
+### Fichiers du projet
+
+```
+cv-web-liabeuf/
+├── index.html            ← Moteur de rendu unique (HTML + CSS + JS)
+├── cv-data.json          ← Version maître (Directeur Conseil Service)
+├── cv-data-ux.json       ← Version UX & Digital Manager
+├── cv-data-dsi.json      ← Version Directeur SI & Transformation Digitale
+├── infrastructure.html   ← Page dédiée à la stack technique du projet
+├── favicon.svg           ← Favicon SVG initiales SL + dégradé Cornerstone CGI
+├── DOCUMENTATION.md      ← Ce fichier
+└── .gitignore            ← Exclut .claude/ (dossier de travail Claude Code)
+```
+
+---
+
+## Versions du CV
+
+Le paramètre `?cv=` dans l'URL permet de charger une version différente du CV sans changer l'URL de base :
+
+| URL | Fichier JSON | Cible |
+|-----|-------------|-------|
+| `cv.stephaneliabeuf.fr` | `cv-data.json` | Version généraliste (défaut) |
+| `cv.stephaneliabeuf.fr?cv=ux` | `cv-data-ux.json` | Recruteurs UX / Digital |
+| `cv.stephaneliabeuf.fr?cv=dsi` | `cv-data-dsi.json` | DSI / Directions SI |
+
+Le paramètre `?cv=` est **transparent** : il n'est pas affiché dans l'interface, seule l'URL change. Il est automatiquement propagé vers la page `infrastructure.html` et conservé lors du retour au CV.
+
+---
+
+## Structure d'un fichier JSON de données
+
+Chaque fichier JSON suit la même structure :
+
+```json
+{
+  "identity": {
+    "prenom": "Stéphane",
+    "nom": "Liabeuf",
+    "titre": "...",
+    "entreprise": "CGI Group",
+    "localisation": "Clermont-Ferrand",
+    "accroche": "...",
+    "description": "...",
+    "disponibilite": "...",
+    "contact": {
+      "email": "",
+      "telephone": "",
+      "linkedin": "https://www.linkedin.com/in/stephaneliabeuf/",
+      "github": "",
+      "site": "https://www.stephaneliabeuf.fr"
+    },
+    "seo": {
+      "title": "...",
+      "description": "...",
+      "keywords": "...",
+      "og_image": "...",
+      "canonical": "..."
+    }
+  },
+  "stats": [ { "valeur": "25+", "label": "années XP" } ],
+  "experiences": [
+    {
+      "groupe": "CGI // Directeur Conseil Service",
+      "groupe_style": "primary",
+      "postes": [
+        {
+          "periode": "...",
+          "entreprise": "...",
+          "role": "...",
+          "programme": "...",
+          "objectif": "...",
+          "description": "...",
+          "resultats": ["..."],
+          "tags": ["Tag:mag", "Tag:grn"]
+        }
+      ]
+    }
+  ],
+  "competences": [
+    {
+      "categorie": "Techniques",
+      "items": [
+        { "nom": "Gestion de projet", "annees": "25A", "niveau": 100, "label": "EXPERT" }
+      ]
+    }
+  ],
+  "secteurs": ["User Experience", "E-Commerce", "..."],
+  "formation": [
+    { "annee": "1999", "diplome": "...", "etablissement": "...", "details": "..." }
+  ],
+  "certifications": ["CMMI", "PMI (2005)", "..."]
+}
+```
+
+### Système de tags colorés
+
+Les tags d'expérience acceptent un suffixe de couleur :
+
+| Syntaxe | Couleur |
+|---------|---------|
+| `"Tag:mag"` | Magenta / accent |
+| `"Tag:grn"` | Vert succès |
+| `"Tag"` (sans suffixe) | Couleur neutre du thème |
+
+---
+
+## Thèmes visuels
+
+Le site propose 4 thèmes accessibles via le **menu burger** (icône ≡ en haut à droite) :
+
+| Thème | Identifiant | Ambiance |
+|-------|------------|---------|
+| ⚡ Cyberpunk | `cyberpunk` | Fond noir, néons cyan/magenta, police Orbitron |
+| 💥 Bande Dessinée | `bd` | Fond papier, bulles, ombres portées, Comic Neue |
+| 💼 IT Professionnel | `itpro` | Bleu corporate, clean, Inter |
+| ◆ CGI | `cgi` | Branding officiel CGI — violet #5236AB, dégradé Cornerstone |
+
+Le thème choisi est persisté en `localStorage` et restauré à chaque visite.
+
+Le **dégradé Cornerstone CGI** (`#E31937 → #A82465 → #5236AB`) est appliqué sur le prénom, les bordures hero, les barres de compétences et les éléments d'accent du thème CGI.
+
+---
+
+## Fonctionnalités
+
+### Navigation & UX
+- **Barre de progression de lecture** — fine barre colorée (adaptée au thème) en `position: fixed; top: 0` qui avance au scroll
+- **Ancre active dans la nav** — `IntersectionObserver` sur les 4 sections, highlight du lien courant
+- **Scroll reveal** — les sections apparaissent en `fadeIn` à l'entrée dans le viewport
+- **Typing effect** — animation de saisie sur le badge "Bienvenue sur le CV en ligne de"
+
+### SEO & partage
+- **Métadonnées OG dynamiques** — `og:title`, `og:description`, `og:image`, `twitter:card` injectés depuis le champ `seo` du JSON, spécifiques à chaque version `?cv=`
+- **Schema.org Person** — données structurées JSON-LD injectées dynamiquement
+- **Favicon SVG** — initiales SL sur fond dégradé Cornerstone, rendu parfait dans tous les navigateurs
+
+### Export
+- **Bouton ⬇ PDF** dans la nav — déclenche `window.print()` avec un CSS `@media print` dédié : fond blanc, typo Georgia, sections lisibles, progress bar et boutons masqués
+
+### Multi-versions
+- **Routing JSON par URL** — `?cv=ux` → `cv-data-ux.json`, `?cv=dsi` → `cv-data-dsi.json`, défaut → `cv-data.json`
+- **Propagation du paramètre** — le lien "Voir mon infrastructure" et le bouton "Retour au CV" conservent le `?cv=` actif
+
+### Page Infrastructure
+- Page `infrastructure.html` décrivant la stack complète : Edition → Forgejo → Coolify → Nginx → HTTPS
+- Lien retour dynamique vers `index.html?cv={param}` via `URLSearchParams`
+- Favicon et bouton retour intégrés
+
+---
+
+## Infrastructure de déploiement
+
+```
+Local (dev)
+  │
+  ├── Antigravity (GUI Git)
+  ├── Claude Code (IA — worktree isolé)
+  │
+  ▼
+Forgejo (forge.stephaneliabeuf.fr)
+  │  Auto-hébergé · Dépôt privé · Historique complet
+  │
+  ▼ webhook push
+Coolify (orchestrateur auto-hébergé)
+  │  Détecte chaque push sur main · Build · Rolling update
+  │
+  ▼
+Conteneur Nginx
+  │  Sert les fichiers statiques (HTML, CSS, JS, JSON, SVG)
+  │
+  ▼
+https://cv.stephaneliabeuf.fr
+  └── SSL/TLS géré par Coolify (Let's Encrypt)
+```
+
+### Workflow de développement
+
+1. **Claude Code** travaille dans un **worktree git isolé** (`/.claude/worktrees/...`)
+2. Les modifications sont commitées et poussées directement sur `main` (pas de PR)
+3. Coolify détecte le push et redéploie automatiquement
+4. Le développeur fait `git pull` en local pour resynchroniser son repo
+
+Le worktree est exclu du dépôt via `.gitignore` (`.claude/`).
+
+---
+
+## Ajouter une nouvelle version de CV
+
+1. Créer `cv-data-{nom}.json` en copiant la structure de `cv-data.json`
+2. Adapter `identity`, `stats`, `experiences`, `competences`, `secteurs`, `formation`
+3. Ajouter `{nom}` à la liste `cvAllowed` dans `index.html` :
+   ```javascript
+   const cvAllowed = ['ux', 'dsi', '{nom}'];
+   ```
+4. Commiter et pusher — Coolify déploie automatiquement
+5. Accès : `https://cv.stephaneliabeuf.fr?cv={nom}`
+
+---
+
+## Ajouter un nouveau thème
+
+1. Dans `index.html`, ajouter un bloc CSS `[data-theme="montheme"] { ... }` en ciblant les sélecteurs existants
+2. Ajouter le bouton dans `#theme-menu` :
+   ```html
+   <button class="theme-btn btn-montheme" onclick="setTheme('montheme')">🎨 MON THÈME</button>
+   ```
+3. Ajouter le style du bouton `.theme-btn.btn-montheme { ... }`
+4. Ajouter `'montheme'` dans la liste de validation de `setTheme()`
+
+---
+
+## Technologies utilisées
+
+| Composant | Technologie |
+|-----------|-------------|
+| Rendu | HTML5 / CSS3 / JS vanilla |
+| Fonts | Google Fonts (Orbitron, Share Tech Mono, Comic Neue, Inter) |
+| Icône | SVG inline (favicon) |
+| Hébergement | Nginx (conteneur Docker via Coolify) |
+| Git | Forgejo (auto-hébergé) |
+| CI/CD | Coolify (webhook → deploy automatique) |
+| SSL | Let's Encrypt via Coolify |
+| Dev IA | Claude Code (Anthropic) |
+| GUI Git | Antigravity |
+
+---
+
+*Documentation — Mai 2026*