SupportCredits — Module Dolibarr pour inno³

Version : 1.23.0 (voir CHANGELOG.md pour l'historique complet) Dépendances : Module Tickets (natif), Module Contrats (natif) Optionnel : Module Kanboard Link (intégration tâches), Module Agenda (tâches planifiées) Compatibilité : Dolibarr 17+ (testé jusqu'à 23.0), PHP 7.4+, MySQL/MariaDB, Cloudron

---

Fonctionnalités

🎟️ Carnets de tickets prépayés

Un carnet = un lot de N tickets acheté par un client avec une date de validité.

• Création manuelle depuis la fiche carnet ou la fiche tiers
• Création automatique quand une commande contenant SUPPORT-XX est validée
  → ex : ligne "SUPPORT-20" en qté 2 crée 2 carnets de 20 tickets chacun
• Durée de validité configurable (défaut : 12 mois)
• Statuts : Brouillon → Actif → Épuisé / Périmé / Annulé
• Notification email au client lors de l'activation (optionnelle ou manuelle)

📊 Décompte et qualification

Sur chaque fiche ticket, l'onglet "Coût tickets" permet de qualifier :

Complexité	Tickets consommés
Simple	1
Moyen	3
Complexe	5

Sélection automatique du carnet : le carnet actif le plus ancien avec un solde suffisant est sélectionné. Un carnet avec 2 tickets restants ne sera jamais débité pour un ticket complexe (coût 5) — il attend un ticket simple.

Correction d'erreur : chaque consommation peut être annulée depuis l'onglet Consommations. Le carnet est automatiquement recrédité.

Option : demander la validation du client avant débit (lien tokenisé par email, page validate_token.php).

🔔 Alertes automatiques

Via le scheduler Dolibarr (ou cron) :

• Alerte seuil bas : quand il reste < 25% des tickets sur le dernier carnet actif
• Alerte expiration : quand un carnet expire dans moins de 60 jours
• Marque automatique des carnets périmés comme STATUS_EXPIRED

📈 Pilotage et reporting

• Vue par client : synthèse carnets + widget "clients à surveiller" (solde < 30% ou expiration < 60j)
• Consommations cross-carnets : historique par client sur 6 mois glissants
• Rapport mensuel (rapport_mensuel.php) : envoi manuel ou programmé par client
• Badge dans la liste tickets : indicateur "🎫 à qualifier" pour les agents internes

🔗 Intégrations

• Fiche commande : bloc des carnets créés depuis cette commande (hook ordercard)
• Fiche tiers : onglet SupportCredits + bloc détaillé (hook thirdpartycard)
• Fiche ticket : onglet Coût tickets + alerte solde (hook ticketcard)
• Liste tickets : bannière solde + colonne qualification (hook ticketlist)
• Kanboard : création automatique de tâche à chaque ticket (optionnel)

---

Installation

Via l'interface Dolibarr (recommandé)

1. Configuration → Modules/Applications → Installer un module externe
2. Uploader module_supportcredits-1.23.0.zip
3. Activer le module dans la liste
4. Configurer via Tickets → Carnets support → Configuration

Via terminal (Cloudron)

cp -r supportcredits/ /app/data/htdocs/custom/
# Les tables SQL se créent automatiquement à l'activation

---

Configuration

Accessible via Tickets → Carnets support → Configuration (admins uniquement).

Paramètre	Défaut	Description
Tickets par carnet	20	Nombre de tickets dans un carnet créé automatiquement
Durée de validité	12 mois	Avant péremption
Seuil alerte tickets	25 %	Déclenche l'alerte si restant < X% sur le dernier carnet
Alerte expiration	60 jours	Prévenance avant péremption
Référence produit	SUPPORT-20	Préfixe déclenchant la création automatique
Notification activation	désactivé	Email client à chaque carnet activé
Validation client	désactivé	Débit suspendu jusqu'à confirmation client
Intégration Kanboard	désactivé	Nécessite module KanboardLink
Mode debug	désactivé	Logs SQL supplémentaires (admins)

---

Produits catalogue

Créer ces produits pour déclencher la création automatique depuis les commandes :

Référence	Libellé	Tickets
SUPPORT-20	Pack support 20 tickets (12 mois)	20
SUPPORT-50	Pack support 50 tickets (12 mois)	50
SUPPORT-10	Pack support 10 tickets (12 mois)	10

---

Tâche planifiée (alertes automatiques)

Option 1 — Scheduler Dolibarr (recommandé)

Si le module Agenda est activé, la tâche apparaît automatiquement dans
Configuration → Tâches planifiées sous le nom :

SupportCredits — Alertes quotidiennes

Activer la tâche et régler la fréquence (défaut : toutes les 24h).

Option 2 — Cron système

0 8 * * * php /app/data/htdocs/custom/supportcredits/scripts/cron_alerts.php \
  >> /var/log/dolibarr_supportcredits.log 2>&1

Sur Cloudron, utiliser le Job Scheduler ou équivalent.

---

Architecture technique

Tables SQL

Table	Description
llx_supportcredits_carnet	Les carnets — un par lot acheté
llx_supportcredits_consumption	Historique des consommations — 1 ligne par ticket qualifié

Fichiers principaux

supportcredits/
├── class/
│   └── supportcarnet.class.php      # Classe métier : CRUD, consommation, annulation
├── core/
│   ├── actions_hooks/
│   │   └── actions_supportcredits.class.php  # Hooks : fiche tiers, ticket, commande, liste
│   ├── modules/
│   │   └── modSupportCredits.class.php       # Descripteur module : droits, menus, hooks, cron
│   └── triggers/
│       └── interface_99_*.class.php          # Triggers : ORDER_VALIDATE, TICKET_CREATE
├── lib/
│   └── supportcredits.lib.php        # Fonctions partagées (préfixe sc_)
├── scripts/
│   └── cron_alerts.php               # Script alertes (CLI + scheduler Dolibarr)
├── sql/
│   ├── llx_supportcredits_carnet.sql
│   └── llx_supportcredits_consumption.sql
├── ajax/
│   └── balance_soc.php               # Endpoint AJAX : solde JSON d'un tiers
├── card.php                          # Fiche carnet (création, consultation, actions)
├── list.php                          # Liste unifiée (carnets, alertes, non rattachés)
├── client_view.php                   # Vue par client + widget pilotage
├── consumptions.php                  # Détail consommations d'un carnet + annulation
├── rapport_mensuel.php               # Rapport mensuel (affichage + envoi email)
├── export.php                        # Export CSV/XLSX
├── tab_thirdparty.php                # Onglet sur fiche tiers
├── tab_ticket.php                    # Onglet qualification sur fiche ticket
├── unlinked_tickets.php              # Gestion des liaisons ticket ↔ carnet
└── validate_token.php                # Page publique (NOLOGIN) — validation client

Principes de conception

• Isolation complète : aucune modification des tables cœur Dolibarr
• Préfixes : tables llx_supportcredits_*, fonctions sc_*, hooks via classe ActionsSupportcredits
• Sécurité : CSRF tokens sur tous les formulaires POST, accessforbidden() sur toutes les pages, dol_escape_htmltag() sur toutes les sorties
• Compatibilité : Dolibarr 17+, PHP 7.4+, MySQL/MariaDB, Cloudron

Logique multi-carnet

consumeForTicket($fk_soc, $complexity)
  → SELECT carnet WHERE solde >= coût ORDER BY date_end ASC LIMIT 1
  → Si aucun résultat : -3 (refus, pas de fragmentation entre carnets)
  → INSERT consumption + UPDATE tickets_used
  → Si solde == 0 après : SET status = EXHAUSTED

Un ticket complexe (coût 5) ne fragmentera jamais sa consommation sur deux carnets. Le carnet avec 2 tickets restants reste ouvert jusqu'à un ticket simple (coût 1) qui peut le vider entièrement.

---

Droits

Droit	Défaut	Description
supportcredits.read	Actif	Lire les carnets et rapports
supportcredits.write	Inactif	Créer, qualifier, annuler
supportcredits.delete	Inactif	Supprimer des carnets

---

Changelog (extrait)

L'historique détaillé est dans CHANGELOG.md. Ci-dessous les jalons historiques.

v1.18.x (avril 2026)

• API REST : endpoints GET /balance/{socid}, GET /carnets/alerts, GET /carnets/balances
• Conformité CSP : migration des scripts JS inline vers fichiers externes
• Suppression des emails hardcodés → MAIN_MAIL_EMAIL_FROM
• Suppression de la contrainte FK sur llx_societe (convention Dolibarr)

v1.5.0

• Correction getNextRef() : utilise MAX(ref) au lieu de MAX(rowid) (séquence correcte)
• Déduplication : consumeOnCarnet() centralisée dans la classe (supprimée de tab_ticket.php)
• Nouvelle méthode cancelConsumption() : annulation + recrédit automatique du carnet
• Hook printFieldListValue + printFieldListTitle : badge "🎫 à qualifier" dans liste tickets
• Hook ordercard : bloc carnets sur la fiche commande client
• Scheduler Dolibarr : $this->cronjobs + méthode SupportCarnet::runCronAlerts()
• PHPDoc complet sur tous les fichiers (@package, @version, @param, @return)
• $_SERVER['PHP_SELF'] échappé via dol_escape_htmltag() dans tous les contextes HTML
• Vérification droit read ajoutée dans printObjectContent

v1.4.0

• Notifications email à l'activation des carnets (trigger + manuel)
• Rapport mensuel par client avec envoi email (rapport_mensuel.php)
• Widget "clients à surveiller" dans la vue globale (client_view.php)
• Consommations cross-carnets (6 mois glissants) sur la vue client
• Menu "Rapport mensuel" dans la navigation
• Option SUPPORTCREDITS_NOTIFY_CARNET_CREATED dans la configuration
• Déduplication buildAllCarnetsTable → sc_build_carnets_recap_html() dans la lib

v1.3.0

• Nettoyage : suppression de 7 fichiers obsolètes
• Emails CRON enrichis avec récapitulatif de tous les carnets actifs

v1.2.x

• Restructuration menus, corrections SQL, double accès client

---

Paternité et provenance

Ce module est basé sur le code fourni par la communauté Open Source — au premier rang duquel le projet Dolibarr ERP/CRM, dont il constitue une œuvre dérivée, ainsi que l'écosystème PHP plus large.

• Développé et maintenu par inno³ — https://inno3.fr — <hello@inno3.fr>
• Développement assisté par Claude Opus 4.8 (Anthropic)

---

Licence

GPL-3.0-or-later — © 2026 inno³ <hello@inno3.fr>

En tant qu'œuvre dérivée de Dolibarr (GPL-3.0-or-later), ce module est distribué sous la même licence. Voir le fichier LICENSE pour le texte complet.