DevOps Dolibarr : tickets FAQ sans casser l’existant

— ## 1. Pourquoi parler de DevOps avec Dolibarr ?

Dolibarr est avant tout un ERP/PG (Gestion Commerciale) open‑source simple à installer et à configurer. Pourtant, dès que l’on commence à le personnaliser (modules, thèmes, API, automatisations), il devient crucial d’appliquer les bonnes pratiques DevOps :

Objectif DevOps Bénéfice concret sur Dolibarr
Automatisation des déploiements Mise à jour des modules sans toucher manuellement la base de données.
Intégration continue (CI) Tests unitaires sur les surcharges PHP/HTML avant de les pousser en prod.
Gestion de la configuration Versionnage des fichiers conf/ et des modèles de tickets.
Monitoring & alertes Détection rapide d’éventuels conflits entre un module « FAQ » et la logique de stock.

En combinant ces principes avec la FAQ/ticketing, vous pouvez offrir un support client fluide tout en gardant votre ERP stable.

2. Le défi : ajouter des tickets FAQ sans casser l’existant

2.1. Risque typique – Collision d’identifiants (ex. champ product_id déjà utilisé par Dolibarr).

  • Modifications directes dans le répertoire htdocs/ → aucune possibilité de rollback.

  • Dépendance à des versions de plugins qui ne sont plus maintenues.

2.2. Approche « sans casser »

Étape Action clé Pourquoi c’est sûr
1️⃣ Fork ou module dédié Créez un module devops_faq qui s’installe via le gestionnaire de modules (ex. dolibarr_businessmanager). Le module reste séparé du core ; vous pouvez le désactiver à tout moment.
2️⃣ Utilisation de l’API interne Plutôt que d’écrire directement dans les tables, exposez des fonctions via les hooks hookHeader, hookFormLauncher, etc. Vous profitez du système de-CHARGE de Dolibarr et évitez les ruptures de schéma.
3️⃣ Tests automatisés Mettez en place PHPUnit (ou phpunit-dolibarr) pour valider les nouvelles routes et les appels API. Les tests échouent avant le merge, vous savez immédiatement si vous avez brisé quelque chose.
4️⃣ Versionnage & CI Intégrez le repo dans GitLab CI ou GitHub Actions → lint, tests, puis déploiement sur un environnement de staging. Vous gardez une trace écrite des changements et vous pouvez revenir à la version précédente en un clic.
5️⃣ Feature toggle Ajoutez un paramètre dans conf/ (devops_faq_enabled) contrôlable via l’admin. Vous pouvez couper le module sans toucher au code, idéal pour les phases de test.

— ## 3. Mise en place concrète d’un système de tickets & FAQ

3.1. Architecture proposée « `

+——————-+ +——————-+
| Front office | HTTP API | Back office (Dolibarr) |
| (React/Vue/HTML) | <——-> | – Service Ticket |
| – Formulaire FAQ | | – Stockage BDD |
+——————-+ +——————-+
^ |
| v
+————–+ +—————–+
| CI/CD Pipeline | ————> | Environnement |
| (Git, Docker) | Déploiement | Staging / Prod |
+——————+ +—————–+



### 3.2. Étapes de développement  
| Étape | Tâche | Outils / Code |

|------|-------|---------------|

| **1️⃣ Création du module** | `php newmodule.php` → `devops_faq` | `module_name` = `devops_faq` |

| **2️⃣ Ajout d’un formulaire FAQ** | ```php\nadd_faq_entry($question,$answer);\n``` | `htdocs/core/forms/frmdevops_faq.php` |

| **3️⃣ Exposition d’une API REST** | `index.php?controller=DevopsFaq` → `getTicketList()`, `createTicket()` | `htdocs/business/devops_faq/class/DevopsFaq` |

| **4️⃣ Front‑end** | Page Vue/React qui consomme `/index.php?controller=DevopsFaq&...` | `src/components/FaqWidget.vue` |

| **5️⃣ CI** | GitLab pipeline : `php -l`, `phpunit`, `docker-compose up -d` | `.gitlab-ci.yml` |

| **6️⃣ Déploiement** | Docker image `myorg/dolibarr-devops-faq:1.2` → `docker-compose.yml` | `docker-compose.yml` |
---  
## 4. Bonnes pratiques pour **ne pas casser l’existant**  
### 4.1. Isolement des bases de données  

- **Création d’un préfixe propre** : `devops_faq_tickets` au lieu de `tickets`.  

- **Utilisation des fonctions de migration** de Dolibarr (`$db->addField`, `$db->execute`).  

- **Sauvegarde automatisée** : `pg_dump/sh` lancé dans le pipeline avant toute migration.
### 4.2. Séparation des routes  

- **Namespace** : `class ControllerDevopsFaq extends BaseController`.  

- **Pref-URL** : `/index.php?controller=DevopsFaq*`.  

- **Pas de重复** : aucune route ne doit empiéter sur `/index.php?controller=Invoice` ou `/index.php?controller=Product`.
### 4.3. Tests unitaires & d’intégration  
```php

public function testCanCreateTicket()

{

    $topic = new DevopsTicket();

    $topic->create([

        'subject'   => 'FAQ générale',

        'content'   => 'Comment modifier un prix ?',

        'author'    => 1,

        'status'    => 0

    ]);
$this->assertNotEmpty($topic->errorMessage);

    $this->assertGreaterThan(0, $topic->id);

}

  • Coverage > 80 % sur les fonctions du module.

  • Tests d’API avec Postman/Newman pour valider les réponses JSON.

4.4. Versionnement sémantique des plugins

Version Signification
1.0.0 Première release fonctionnelle (feature flag désactivé).
1.1.0 Ajout d’une nouvelle méthode dans l’API (compatibilité ascendante).
2.0.0 Breaking change (ex. renommage de table).

5. FAQ typiques (et réponses)

Question Réponse rapide
Q1 : Où placer les nouvelles tables ? Créez‑les dans votre propre schéma (devops_faq_) ou ajoutez un préfixe au nom de la table dans $_TABLE du module.
Q2 : Le nouveau module fonctionne sur le serveur de prod ? Déployez d’abord en staging via CI, effectuez un rollback automatique en cas d’erreur (exit 1).
Q3 : Puis‑je désactiver le module sans perdre les tickets déjà créés ? Oui. Les tickets sont stockés dans une table séparée. La désactivation ne touche que le code d’accès ; les données restent en base.
Q4 : Comment éviter les conflits de CSS avec le thème d’origine ? Utilisez un namespace de classe (class DevopsFaqTemplate extends Template) ou injectez votre style avec css dans le hook hookHeader.
Q5 : Est‑il possible de garder la même URL d’accès que les tickets natifs de Dolibarr ? Non recommandé. Ajoutez un chemin dédié (/faq) afin d’éviter les collisions avec les modules existants.
Q6 : Les mises à jour de Dolibarr écraseront‑elles mon module ? Tant que vous utilisez le gestionnaire de modules et ne touchez pas aux fichiers du core (sauf via les hooks), les mises à jour n’impactent pas votre code.

6. Exemple de déploiement Dockerisé (tout‑en‑un)

# docker-compose.yml

version: "3.8"

services:

  db:

    image: mariadb:10.11

    environment:

      MYSQL_DATABASE: dolibarr

      MYSQL_USER: dolibarr

      MYSQL_PASSWORD: dolibarr

    volumes:

      - db_data:/var/lib/mysql
php:

    build: ./php

    depends_on:

      - db

    environment:

      - APACHE_DOCUMENT_ROOT=/var/www/html/htdocs

    volumes:

      - ./php/htdocs:/var/www/html/htdocs

    ports:

      - "8080:80"
volumes:

  db_data:

  1. Build : docker-compose build php

  2. Installation de Dolibarr (ou restauration d’un backup) → module devops_faq activé via l’admin.

  3. CI : docker-compose up -d → phpunit s’exécute dans le conteneur → test passe → déploiement sur serveur de prod avec docker pull myorg/dolibarr-devops-faq:latest && docker compose up -d.

7. Checklist finale avant de pousser en production

✅ Item
1 Module installé via le Business Manager (pas de fichiers en htdocs directement).
2 Tous les champs ajoutés sont créés via les fonctions $db->addField.
3 Tests unitaires passent (phpunit → 0 error).
4 Documentation du hook et du endpoint API mise à jour dans le README.md.
5 Feature toggle devops_faq_enabled réglé sur off par défaut.
6 Backup DB pris avant migration (script backup.sh).
7 Déploiement automatisé sur staging avec rollback en cas d’échec.
8 Monitoring (Prometheus + Grafana) activé pour suivre les appels /api/devops_faq.
9 Communication avec l’équipe support : le module est versionné et documenté.

8. Conclusion En appliquant les principes DevOps à un système de tickets/FAQ sous Dolibarr, vous obtenez :

  • Stabilité – aucune modification directe du core.

  • Traçabilité – chaque évolution versionnée, testée et auditée.

  • Résilience – rollback instantané et feature toggles pour les phases de validation.

Le résultat ? Un support client fluide et une FAQ dynamique, sans crainte de casser votre ERP existant.

À retenir : Isoler, automatiser, tester, versionner.
Si chaque étape de votre pipeline répond à ces trois piliers, vous êtes assuré que vos nouvelles FAQ/tickets s’intégreront sans heurt à Dolibarr.

Auteur : [Prénom Nom] – DevOps Engineer & Dolibarr Specialist Date : 3 novembre 2025
Version : 1.2 (compatible Dolibarr 23.x)

Publications similaires