Module Campagnes SMS¶

Objectif¶

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

Le perimetre documente ici couvre :

la configuration des URLs applicatives utilisees par le frontend ;
la creation d'une campagne SMS ;
la gestion d'un echec de creation cote interface ;
l'affichage des statistiques detaillees ;
le traitement des SMS non recus ;
le blocage/deblocage de numeros en echec ;
le masquage du plan Demo dans les interfaces d'abonnement ;
les workflows de deploiement frontend/backoffice associes 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 implique 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 creation campagne
  - liste et filtres
  - detail statistique
  - achat SMS
  |
  | HTTP JSON
  v
API d'integration
  - /campaigns
  - /all_campaigns
  - /statistique/campaigns/{id}
  - /contacts/block
  |
  v
Fournisseur SMS / donnees 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 exposees 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 utilisee pour certains assets bibliotheque/documents ;
normalizeBackendAssetUrl : remplace les URLs localhost et les chemins /uploads par une URL backend exploitable en environnement deploye.

Point de reprise : toute nouvelle integration frontend doit passer par appUrls.ts plutot que dupliquer une URL dans un composant.

Creation d'une campagne¶

Fichier :

frontend/solu/src/components/CampagnePage.tsx

Le composant gere un assistant en 5 etapes :

nom de campagne ;
contacts ;
message ;
planification ;
resume.

Etat principal :

campagneData
  nom
  marketingPurpose
  pushtype
  contacts
  contactsValides
  expediteur
  message
  messageLength
  smsCount
  planification

Le societe_id envoye a l'API est lu depuis localStorage.getItem("membreId"), converti en nombre, puis assigne a societe_id dans le payload. Ce nommage est trompeur : le code lit une cle appelee membreId, mais l'envoie comme identifiant de societe. Avant toute modification de ce flux, verifier le contrat reel attendu par l'API d'integration.

Endpoint appele :

POST {INTEGRATION_API_URL}/campaigns

Payload construit :

name
message
pushtype
links
sender
societe_id
sent_at
scheduled_at
contacts ou list_contact_id

Regles 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 differe, la date planifiee doit etre dans le futur ;
pour un envoi immediat, le code force scheduled_at a environ une minute dans le futur.

Gestion des echecs de creation¶

La reponse de creation est consideree en echec si :

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

Type d'erreur attendu cote frontend :

success
message
details
campaign_id
campaign_status
credits.local_available
credits.required

Le message affiche combine :

details ou message ;
les credits Solutravo disponibles ;
les credits necessaires ;
l'identifiant de campagne quand l'API a quand meme enregistre une campagne en echec.

Le composant SuccessPopup a ete generalise pour supporter deux variantes :

success ;
error.

En cas d'echec 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 a /all_campaigns :

Filtre UI	Parametre 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 reussite ;
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 recus¶

Fichier :

frontend/solu/src/components/CampagneDetails.tsx

Le composant charge les details avec getCampagneDetails(campagneId) puis transforme :

detail_stat.clicked en liste de cliqueurs ;
detail_stat.failed en liste de SMS non recus.

La transformation des echecs accepte plusieurs noms de champs issus des reponses backend/SMS :

numero : 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 generique, l'interface affiche un message support exploitable plutot qu'une valeur technique inutile.

Blacklist des numeros¶

Depuis le detail de campagne, l'utilisateur peut bloquer ou debloquer :

un numero individuel ;
tous les numeros en echec non encore bloques.

Endpoint :

POST {INTEGRATION_API_URL}/contacts/block

Payload :

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

Le tableau local est mis a jour apres succes de l'appel API. Si l'appel echoue, l'interface affiche l'erreur issue de l'exception ou un message de secours.

Header campagnes et credits SMS¶

Fichier :

frontend/solu/src/components/HeaderCampagne.tsx

Le header charge les credits 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 societes ayant le role artisan, avant de retourner la liste des plans.

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

Deploiement¶

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_* injectees au build.

Deploiement :

staging : FTP vers l'hebergement configure pour franck_staging ;
production : FTP vers l'hebergement configure pour prod_franck ;
dangerous-clean-slate: true est active sur le deploiement staging.

Workflow backend :

.github/workflows/deploy-backend.yml

Les commits examines sur ce perimetre montrent surtout des corrections de script de deploiement : renommage du workflow, scripts staging/prod, exclusions rsync, slash final de server-dir, et prevention de preservation owner/group/perms.

Points d'attention pour reprise¶

membreId dans le localStorage est utilise comme societe_id dans plusieurs appels. Ne pas renommer sans verifier l'API et les donnees stockees dans le navigateur.
Les composants utilisent window.location.href pour certains retours de flux. Une migration vers navigation React doit verifier les rechargements attendus.
SuccessPopup n'est plus limite au succes : il sert aussi aux echecs. Toute modification de style doit conserver les variantes success et error.
L'API peut repondre success: false avec un HTTP 2xx. Le frontend verifie les deux signaux ; garder cette double verification.
Le workflow frontend contient une cle API injectee directement dans la configuration de build. Avant publication publique durable ou reprise de deploiement, deplacer cette valeur dans un secret GitHub, faire une rotation de la cle et ne pas la documenter en clair.
Le plan Demo est masque par nom. Si le nom du plan change, le filtre ne fonctionnera plus. Preferer a terme un identifiant technique ou un flag de visibilite dans l'API.