Aller au contenu

Module Campagnes SMS

Objectif

Le module Campagnes SMS permet de créer, planifier et suivre des campagnes SMS depuis l'application React frontend/solu.

Le périmètre documenté ici couvre :

  • la configuration des URLs applicatives utilisées par le frontend ;
  • la création d'une campagne SMS ;
  • la gestion d'un échec de création côté interface ;
  • l'affichage des statistiques détaillées ;
  • le traitement des SMS non reçus ;
  • le blocage/déblocage de numéros en échec ;
  • le masquage du plan Demo dans les interfaces d'abonnement ;
  • les workflows de déploiement frontend/backoffice associés aux branches franck_staging et prod_franck.

Emplacement du code

Fichiers frontend principaux :

frontend/solu/src/components/CampagnePage.tsx
frontend/solu/src/components/CampagneDetails.tsx
frontend/solu/src/components/HeaderCampagne.tsx
frontend/solu/src/components/SuccessPopup.tsx
frontend/solu/src/services/filtresCampagnesData.ts
frontend/solu/src/types/campagne.types.ts
frontend/solu/src/config/appUrls.ts
frontend/solu/src/styles/success-popup.css
frontend/solu/src/components/SubscriptionPage.tsx

Fichier backend impliqué pour les abonnements :

backend/src/controllers/CheckSubscriptionControllers.ts

Workflows :

.github/workflows/deploy-frontend.yml
.github/workflows/deploy-backend.yml

Vue d'ensemble architecture

Utilisateur
  |
  v
Frontend React frontend/solu
  - assistant de création campagne
  - liste et filtres
  - detail statistique
  - achat SMS
  |
  | HTTP JSON
  v
API d'intégration
  - /campaigns
  - /all_campaigns
  - /statistique/campaigns/{id}
  - /contacts/block
  |
  v
Fournisseur SMS / données campagne

Le frontend ne construit pas directement les URLs en dur dans les composants. Les endpoints principaux passent par frontend/solu/src/config/appUrls.ts.

Configuration des URLs

Fichier :

  • frontend/solu/src/config/appUrls.ts

Le helper getEnvUrl lit les variables VITE_*, retire les slashs de fin et applique un fallback si la variable est absente.

Variables exposées au build :

VITE_SOLUTRAVO_API_URL
VITE_SOLUTRAVO_BACKEND_URL
VITE_INTEGRATION_API_URL
VITE_WEB_APP_URL
VITE_AUTH_APP_URL
VITE_DASHBOARD_URL
VITE_MICROSERVICE_LOGIN_URL
VITE_MARKETING_SITE_URL
VITE_SCRAPIO_API_URL
VITE_LARAVEL_API_URL
VITE_PRODUCT_IMAGES_BASE_URL
VITE_LIBRARY_IMAGES_BASE_URL
VITE_PRODUCT_DOCUMENTS_BASE_URL
VITE_CATALOGUE_IMAGES_BASE_URL

Constantes importantes :

  • INTEGRATION_API_URL : base des appels campagnes SMS ;
  • SOLUTRAVO_BACKEND_URL : base des assets exposes par le backend historique ;
  • LARAVEL_API_URL : base utilisée pour certains assets bibliothèque/documents ;
  • normalizeBackendAssetUrl : remplace les URLs localhost et les chemins /uploads par une URL backend exploitable en environnement déployé.

Point de reprise : toute nouvelle intégration frontend doit passer par appUrls.ts plutôt que dupliquer une URL dans un composant.

Création d'une campagne

Fichier :

  • frontend/solu/src/components/CampagnePage.tsx

Le composant gère un assistant en 5 etapes :

  1. nom de campagne ;
  2. contacts ;
  3. message ;
  4. planification ;
  5. résumé.

Etat principal :

campagneData
  nom
  marketingPurpose
  pushtype
  contacts
  contactsValides
  expediteur
  message
  messageLength
  smsCount
  planification

Le societe_id envoyé à l'API est lu depuis localStorage.getItem("membreId"), converti en nombre, puis assigné à societe_id dans le payload. Ce nommage est trompeur : le code lit une clé appelée membreId, mais l'envoie comme identifiant de société. Avant toute modification de ce flux, vérifier le contrat réel attendu par l'API d'intégration.

Endpoint appelé :

POST {INTEGRATION_API_URL}/campaigns

Payload construit :

name
message
pushtype
links
sender
societe_id
sent_at
scheduled_at
contacts ou list_contact_id

Règles visibles :

  • si le contact type est manuelle, le payload contient contacts et list_contact_id = null ;
  • si le contact type est enregistres, le payload contient list_contact_id et contacts = null ;
  • pour un envoi différé, la date planifiee doit être dans le futur ;
  • pour un envoi immédiat, le code force scheduled_at a environ une minute dans le futur.

Gestion des échecs de création

La réponse de création est considérée en échec si :

  • le statut HTTP n'est pas OK ;
  • ou le JSON contient success: false.

Type d'erreur attendu côté frontend :

success
message
details
campaign_id
campaign_status
crédits.local_available
crédits.required

Le message affiche combine :

  • details ou message ;
  • les crédits Solutravo disponibles ;
  • les crédits nécessaires ;
  • l'identifiant de campagne quand l'API a quand même enregistre une campagne en échec.

Le composant SuccessPopup a été generalise pour supporter deux variantes :

  • success ;
  • error.

En cas d'échec avec campaign_id, l'utilisateur peut aller vers :

/statistique/campaigns/{campaign_id}

Sinon, la fermeture ramene a la liste :

/campagne/{userId}

Liste et statistiques de campagne

Fichier :

  • frontend/solu/src/services/filtresCampagnesData.ts

Endpoints :

GET {INTEGRATION_API_URL}/all_campaigns?societe_id={id}&page={page}
GET {INTEGRATION_API_URL}/statistique/campaigns/{campaignId}

Filtres transmis à /all_campaigns :

Filtre UI Paramètre API
telephone phone_number
smsMin min_people
smsMax max_people
message message
dateDebut dateDebut
dateFin dateFin
supprimees supprimees=true

Le service calcule aussi des statistiques locales depuis les recipients :

  • total ;
  • delivered ;
  • pending ;
  • failed ;
  • clicked ;
  • stopped ;
  • taux de réussite ;
  • taux de clics.

Statuts globaux calcules :

  • completed si tous les recipients sont delivered ;
  • failed si tous les recipients sont failed ;
  • pending si au moins un recipient est pending ou si la liste est vide.

Detail des SMS non reçus

Fichier :

  • frontend/solu/src/components/CampagneDetails.tsx

Le composant charge les détails avec getCampagneDetails(campagneId) puis transforme :

  • detail_stat.clicked en liste de cliqueurs ;
  • detail_stat.failed en liste de SMS non reçus.

La transformation des échecs accepte plusieurs noms de champs issus des réponses backend/SMS :

  • numéro : phone_number ou phone ;
  • raison : raison, reason, error_message, details ou message ;
  • date : failed_at, sent_at, created_at, updated_at ou date_echec.

Si la raison est absente ou trop générique, l'interface affiche un message support exploitable plutôt qu'une valeur technique inutile.

Blacklist des numéros

Depuis le détail de campagne, l'utilisateur peut bloquer ou debloquer :

  • un numéro individuel ;
  • tous les numéros en échec non encore bloques.

Endpoint :

POST {INTEGRATION_API_URL}/contacts/block

Payload :

{
  "phone_number": ["0612345678"],
  "societe_id": 123,
  "block": true
}

Le tableau local est mis à jour après succès de l'appel API. Si l'appel échoue, l'interface affiche l'erreur issue de l'exception ou un message de secours.

Header campagnes et crédits SMS

Fichier :

  • frontend/solu/src/components/HeaderCampagne.tsx

Le header charge les crédits via getUserCredits(membreId) puis affiche :

  • le nombre de SMS restants ;
  • le nom utilisateur ;
  • le compte courant ;
  • un bouton vers /campagne/{membreId}/achat-sms.

Le nombre affiche priorise remaining_credits, puis credits, puis 0.

Masquage du plan Demo

Fichiers :

  • frontend/solu/src/components/SubscriptionPage.tsx
  • backend/src/controllers/CheckSubscriptionControllers.ts

Le plan Demo est masque des interfaces d'abonnement artisan.

Cote frontend, SubscriptionPage.tsx filtre les plans dont le nom normalise vaut demo.

Cote backend, CheckSubscriptionControllers.ts applique aussi le filtre pour les sociétés ayant le rôle artisan, avant de retourner la liste des plans.

Point de reprise : garder le filtre côté backend. Le filtre frontend ameliore l'UX, mais ne suffit pas si un autre client consomme l'endpoint.

Déploiement

Workflow frontend :

  • .github/workflows/deploy-frontend.yml

Declencheurs :

  • workflow_dispatch ;
  • push sur franck_staging ;
  • push sur prod_franck ;
  • uniquement si frontend/solu/** ou le workflow frontend changent.

Build :

  • Node 20.19.4 ;
  • cache npm sur frontend/solu/package-lock.json ;
  • npm ci ;
  • npm run build ;
  • variables VITE_* injectées au build.

Déploiement :

  • staging : FTP vers l'hébergement configuré pour franck_staging ;
  • production : FTP vers l'hébergement configuré pour prod_franck ;
  • dangerous-clean-slate: true est activé sur le déploiement staging.

Workflow backend :

  • .github/workflows/deploy-backend.yml

Les commits examinés sur ce périmètre montrent surtout des corrections de script de déploiement : renommage du workflow, scripts staging/prod, exclusions rsync, slash final de server-dir, et prévention de préservation owner/group/perms.

Points d'attention pour reprise

  • membreId dans le localStorage est utilise comme societe_id dans plusieurs appels. Ne pas renommer sans vérifier l'API et les données stockees dans le navigateur.
  • Les composants utilisent window.location.href pour certains retours de flux. Une migration vers navigation React doit vérifier les rechargements attendus.
  • SuccessPopup n'est plus limité au succès : il sert aussi aux échecs. Toute modification de style doit conserver les variantes success et error.
  • L'API peut repondre success: false avec un HTTP 2xx. Le frontend vérifie les deux signaux ; garder cette double vérification.
  • Le workflow frontend contient une clé API injectée directement dans la configuration de build. Avant publication publique durable ou reprise de déploiement, déplacer cette valeur dans un secret GitHub, faire une rotation de la clé et ne pas la documenter en clair.
  • Le plan Demo est masqué par nom. Si le nom du plan change, le filtre ne fonctionnera plus. Préférer à terme un identifiant technique ou un flag de visibilité dans l'API.