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
Demodans les interfaces d'abonnement ; - les workflows de déploiement frontend/backoffice associés aux branches
franck_stagingetprod_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 :
Workflows :
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/uploadspar 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 :
- nom de campagne ;
- contacts ;
- message ;
- planification ;
- 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é :
Payload construit :
Règles visibles :
- si le contact type est
manuelle, le payload contientcontactsetlist_contact_id = null; - si le contact type est
enregistres, le payload contientlist_contact_idetcontacts = null; - pour un envoi différé, la date planifiee doit être dans le futur ;
- pour un envoi immédiat, le code force
scheduled_ata 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 :
Le message affiche combine :
detailsoumessage;- 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 :
Sinon, la fermeture ramene a la liste :
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 :
completedsi tous les recipients sontdelivered;failedsi tous les recipients sontfailed;pendingsi au moins un recipient estpendingou 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.clickeden liste de cliqueurs ;detail_stat.faileden liste de SMS non reçus.
La transformation des échecs accepte plusieurs noms de champs issus des réponses backend/SMS :
- numéro :
phone_numberouphone; - raison :
raison,reason,error_message,detailsoumessage; - date :
failed_at,sent_at,created_at,updated_atoudate_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 :
Payload :
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.tsxbackend/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: trueest 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¶
membreIddans le localStorage est utilise commesociete_iddans plusieurs appels. Ne pas renommer sans vérifier l'API et les données stockees dans le navigateur.- Les composants utilisent
window.location.hrefpour certains retours de flux. Une migration vers navigation React doit vérifier les rechargements attendus. SuccessPopupn'est plus limité au succès : il sert aussi aux échecs. Toute modification de style doit conserver les variantessuccesseterror.- L'API peut repondre
success: falseavec 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
Demoest 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.