docs: add descriptive titles and comments to Jenkinsfile

- Add header documentation explaining all pipeline stages
- Add detailed comments for each stage explaining purpose and actions
- Add emoji icons to stage names for better visibility in Jenkins UI
- Add success/failure banners with configuration details

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Jenkinsfile

@@ -1,10 +1,41 @@
+/**
+ * ============================================================================
+ * PIPELINE CI/CD - THÉ TIP TOP BACKEND
+ * ============================================================================
+ *
+ * Ce pipeline automatise le processus de déploiement continu du backend.
+ *
+ * ÉTAPES DU PIPELINE :
+ * 1. Init          - Détection de l'environnement (dev/preprod/prod)
+ * 2. Checkout      - Récupération du code source depuis Git
+ * 3. Install       - Installation des dépendances Node.js
+ * 4. Quality       - Vérification qualité (ESLint + Jest + SonarQube)
+ * 5. Build         - Construction de l'image Docker
+ * 6. Push          - Envoi de l'image vers le registre Docker privé
+ * 7. Backup        - Sauvegarde de la base de données (prod uniquement)
+ * 8. Deploy        - Déploiement sur le serveur cible
+ *
+ * ENVIRONNEMENTS :
+ * - dev     : Développement (branche dev)
+ * - preprod : Pré-production (branche preprod)
+ * - prod    : Production (branche main)
+ *
+ * ============================================================================
+ */
+
 pipeline {
     agent any
 
+    // =========================================================================
+    // DÉCLENCHEUR : Vérifie les changements Git chaque minute
+    // =========================================================================
     triggers {
         pollSCM('* * * * *')
     }
 
+    // =========================================================================
+    // PARAMÈTRES : Permet de choisir manuellement l'environnement
+    // =========================================================================
     parameters {
         choice(
             name: 'ENV',
@@ -13,6 +44,9 @@ pipeline {
         )
     }
 
+    // =========================================================================
+    // VARIABLES D'ENVIRONNEMENT GLOBALES
+    // =========================================================================
     environment {
         REGISTRY_URL = "registry.wk-archi-o24a-15m-g3.fr"
         IMAGE_NAME = "the-tip-top-backend"
@@ -21,7 +55,15 @@ pipeline {
 
     stages {
 
-        stage('Init') {
+        // =====================================================================
+        // ÉTAPE 1 : INITIALISATION
+        // ---------------------------------------------------------------------
+        // But : Détecter automatiquement l'environnement selon la branche Git
+        // - Branche 'dev'     → Environnement dev
+        // - Branche 'preprod' → Environnement preprod
+        // - Branche 'main'    → Environnement prod
+        // =====================================================================
+        stage('🧭 Init - Détection environnement') {
             steps {
                 script {
                     def currentBranch = sh(script: "git rev-parse --abbrev-ref HEAD", returnStdout: true).trim()
@@ -37,22 +79,41 @@ pipeline {
                     env.DEPLOY_PATH = "/srv/devops/the-tip-top/${env.ENV}"
 
                     echo """
-                    🌍 Environnement = ${env.ENV}
+                    ╔══════════════════════════════════════════╗
-                    🏷️ Tag Docker = ${env.TAG}
+                    ║         CONFIGURATION PIPELINE           ║
-                    📂 Chemin de déploiement = ${env.DEPLOY_PATH}
+                    ╠══════════════════════════════════════════╣
+                    ║ 🌍 Environnement    : ${env.ENV.padRight(18)} ║
+                    ║ 🏷️  Tag Docker       : ${env.TAG.padRight(18)} ║
+                    ║ 📂 Chemin déploie.  : ${env.DEPLOY_PATH.take(18).padRight(18)} ║
+                    ╚══════════════════════════════════════════╝
                     """
                 }
             }
         }
 
-        stage('Checkout') {
+        // =====================================================================
+        // ÉTAPE 2 : CHECKOUT
+        // ---------------------------------------------------------------------
+        // But : Récupérer le code source depuis le dépôt Gitea
+        // Action : Clone ou pull du code selon l'état du workspace
+        // =====================================================================
+        stage('📦 Checkout - Récupération code source') {
             steps {
-                echo "📦 Récupération du code source..."
+                echo "📦 Récupération du code source depuis Gitea..."
                 checkout scm
+                echo "✅ Code source récupéré avec succès"
             }
         }
 
-        stage('Install Dependencies') {
+        // =====================================================================
+        // ÉTAPE 3 : INSTALLATION DES DÉPENDANCES
+        // ---------------------------------------------------------------------
+        // But : Installer les packages Node.js nécessaires
+        // Container : node:18-alpine (léger et rapide)
+        // Commande : npm ci (installation propre depuis package-lock.json)
+        // Cache : Utilise un cache NPM partagé pour accélérer les builds
+        // =====================================================================
+        stage('📦 Install - Dépendances Node.js') {
             agent {
                 docker {
                     image 'node:18-alpine'
@@ -60,15 +121,30 @@ pipeline {
                 }
             }
             steps {
-                echo "📦 Installation des dépendances..."
+                echo "📦 Installation des dépendances Node.js..."
                 sh 'npm ci --prefer-offline'
                 stash includes: 'node_modules/**', name: 'node_modules'
+                echo "✅ Dépendances installées avec succès"
             }
         }
 
-        stage('Quality Checks') {
+        // =====================================================================
+        // ÉTAPE 4 : CONTRÔLES QUALITÉ (Exécution parallèle)
+        // ---------------------------------------------------------------------
+        // Exécute en parallèle :
+        // - Lint & Tests : ESLint + Jest avec couverture de code
+        // - SonarQube : Analyse statique de la qualité du code
+        // =====================================================================
+        stage('🔍 Quality - Contrôles qualité') {
             parallel {
-                stage('Lint & Tests') {
+                // -------------------------------------------------------------
+                // 4a. LINT & TESTS
+                // -------------------------------------------------------------
+                // ESLint : Vérifie le style et les erreurs de code
+                // Jest : Exécute les tests unitaires et d'intégration
+                // Couverture : Génère un rapport de couverture (lcov)
+                // -------------------------------------------------------------
+                stage('🧪 Lint & Tests') {
                     agent {
                         docker {
                             image 'node:18-alpine'
@@ -77,23 +153,32 @@ pipeline {
                     }
                     steps {
                         unstash 'node_modules'
-                        echo "🧪 Lancement des tests et lint..."
+                        echo "🧪 Lancement ESLint et Jest..."
                         script {
                             def lintStatus = sh(script: 'npm run lint', returnStatus: true)
                             def testStatus = sh(script: 'npm test', returnStatus: true)
 
                             if (lintStatus != 0) {
-                                error "❌ ESLint a échoué"
+                                error "❌ ESLint a échoué - Corrigez les erreurs de style"
                             }
                             if (testStatus != 0) {
-                                error "❌ Les tests ont échoué"
+                                error "❌ Les tests ont échoué - Vérifiez les tests unitaires"
                             }
-                            echo "✅ Tests et lint passés"
+                            echo "✅ Lint et tests passés avec succès"
                         }
                     }
                 }
 
-                stage('SonarQube') {
+                // -------------------------------------------------------------
+                // 4b. SONARQUBE
+                // -------------------------------------------------------------
+                // Analyse statique du code pour détecter :
+                // - Bugs potentiels
+                // - Vulnérabilités de sécurité
+                // - Code smells (mauvaises pratiques)
+                // - Couverture de code insuffisante
+                // -------------------------------------------------------------
+                stage('📊 SonarQube Analysis') {
                     agent {
                         docker {
                             image 'sonarsource/sonar-scanner-cli:latest'
@@ -101,30 +186,47 @@ pipeline {
                         }
                     }
                     steps {
-                        echo "🔍 Analyse SonarQube..."
+                        echo "📊 Analyse SonarQube en cours..."
                         withSonarQubeEnv('SonarQube') {
                             sh """
                                 sonar-scanner
                             """
                         }
+                        echo "✅ Analyse SonarQube terminée"
                     }
                 }
             }
         }
 
-        stage('Build Docker image') {
+        // =====================================================================
+        // ÉTAPE 5 : BUILD IMAGE DOCKER
+        // ---------------------------------------------------------------------
+        // But : Construire l'image Docker du backend
+        // Tags créés :
+        // - {env}-latest (ex: dev-latest, prod-latest)
+        // - latest
+        // =====================================================================
+        stage('🐳 Build - Image Docker') {
             steps {
                 echo "🐳 Construction de l'image Docker backend..."
                 sh """
                     docker build -t ${REGISTRY_URL}/${IMAGE_NAME}:${TAG} .
                     docker tag ${REGISTRY_URL}/${IMAGE_NAME}:${TAG} ${REGISTRY_URL}/${IMAGE_NAME}:latest
                 """
+                echo "✅ Image Docker construite : ${REGISTRY_URL}/${IMAGE_NAME}:${TAG}"
             }
         }
 
-        stage('Push to Registry') {
+        // =====================================================================
+        // ÉTAPE 6 : PUSH VERS LE REGISTRE
+        // ---------------------------------------------------------------------
+        // But : Envoyer l'image Docker vers le registre privé
+        // Registre : registry.wk-archi-o24a-15m-g3.fr
+        // Authentification : Credentials Jenkins sécurisés
+        // =====================================================================
+        stage('📤 Push - Registre Docker') {
             steps {
-                echo "📤 Envoi de l'image vers le registre..."
+                echo "📤 Envoi de l'image vers le registre Docker privé..."
                 withCredentials([usernamePassword(credentialsId: 'registry-credentials', usernameVariable: 'REG_USER', passwordVariable: 'REG_PASS')]) {
                     sh """
                         echo "$REG_PASS" | docker login ${REGISTRY_URL} -u "$REG_USER" --password-stdin
@@ -132,40 +234,77 @@ pipeline {
                         docker push ${REGISTRY_URL}/${IMAGE_NAME}:latest
                     """
                 }
+                echo "✅ Image envoyée avec succès vers ${REGISTRY_URL}"
             }
         }
 
-        stage('Backup DB') {
+        // =====================================================================
+        // ÉTAPE 7 : BACKUP BASE DE DONNÉES (Production uniquement)
+        // ---------------------------------------------------------------------
+        // But : Sauvegarder la base de données avant le déploiement
+        // Condition : Seulement en environnement de production
+        // Script : /srv/devops/the-tip-top/backup.sh
+        // Sécurité : Continue même si le backup échoue (warning)
+        // =====================================================================
+        stage('💾 Backup - Base de données') {
             when {
                 expression { env.ENV == 'prod' }
             }
             steps {
-                echo "💾 Backup de la base de données avant déploiement..."
+                echo "💾 Sauvegarde de la base de données PostgreSQL..."
                 sh """
                     /srv/devops/the-tip-top/backup.sh || echo "⚠️ Backup échoué mais on continue"
                 """
-                echo "✅ Backup terminé"
+                echo "✅ Backup de la base de données terminé"
             }
         }
 
-        stage('Deploy') {
+        // =====================================================================
+        // ÉTAPE 8 : DÉPLOIEMENT
+        // ---------------------------------------------------------------------
+        // But : Déployer le backend sur le serveur cible
+        // Actions :
+        // 1. Pull de la nouvelle image depuis le registre
+        // 2. Recréation du container avec la nouvelle image
+        // Chemins : /srv/devops/the-tip-top/{dev|preprod|prod}
+        // =====================================================================
+        stage('🚀 Deploy - Mise en production') {
             steps {
-                echo "🚀 Déploiement sur ${env.ENV}..."
+                echo "🚀 Déploiement du backend sur l'environnement ${env.ENV}..."
                 sh """
                     cd "${DEPLOY_PATH}"
                     docker compose pull backend
                     docker compose up -d --force-recreate backend
                 """
+                echo "✅ Backend déployé avec succès sur ${env.ENV}"
             }
         }
     }
 
+    // =========================================================================
+    // ACTIONS POST-PIPELINE
+    // =========================================================================
     post {
         success {
-            echo "✅ Pipeline ${env.ENV} terminé avec succès !"
+            echo """
+            ╔══════════════════════════════════════════╗
+            ║     ✅ PIPELINE TERMINÉ AVEC SUCCÈS     ║
+            ╠══════════════════════════════════════════╣
+            ║ Environnement : ${env.ENV.padRight(23)} ║
+            ║ Image         : ${IMAGE_NAME.padRight(23)} ║
+            ║ Tag           : ${env.TAG.padRight(23)} ║
+            ╚══════════════════════════════════════════╝
+            """
         }
         failure {
-            echo "❌ Échec du pipeline ${env.ENV}."
+            echo """
+            ╔══════════════════════════════════════════╗
+            ║        ❌ ÉCHEC DU PIPELINE             ║
+            ╠══════════════════════════════════════════╣
+            ║ Environnement : ${env.ENV.padRight(23)} ║
+            ║ Vérifiez les logs pour plus de détails  ║
+            ╚══════════════════════════════════════════╝
+            """
         }
     }
 }