Installer et exploiter votre plateforme MutualBoost de A à Z.
Documentation CLIENT approfondie : prérequis, hébergement, activation, gestion de la mutuelle, Flutter, OneSignal/FCM/APNs, paiements, supervision, mises à jour signées et restauration.
Version documentaire : 18 octobre 2026 · guide approfondi complet · 28 chapitres pratiques
Suivez ce parcours avec les accès fournis par votre éditeur. La licence couvre votre installation ; vos adhérents se connectent ensuite avec leur compte habituel.
La recherche filtre les chapitres de cette page. Effacez votre recherche pour retrouver tout le guide.
28 chapitre(s) affiché(s)
Aucun chapitre ne correspond. Essayez « Laravel », « Flutter » ou « paiement ».
01
Comprendre les deux distributions
Distinguer le serveur éditeur de la plateforme installée chez chaque mutuelle.
ÉDITEUR : rôle exclusif de GBAMA CODES
La distribution ÉDITEUR pilote l’émission de licences, les achats Envato, le portefeuille des installations et les publications logicielles signées. Elle s’installe sur une instance Laravel dédiée comme licences.mondomaine.com et protège ses clés privées hors du répertoire public.
CLIENT : rôle de chaque mutuelle
Chaque mutuelle dispose de sa propre installation Laravel (mondomaine.com), de sa base de données et de sa configuration. Le Web et Flutter consomment ce serveur unique ; une licence logicielle protège l’installation, pas chaque adhérent.
Distinguer sources cumulatives et projets autonomes
Les ZIP de cette livraison regroupent des fichiers applicatifs à fusionner avec un Laravel complet. Il leur manque le squelette verrouillé (artisan, composer.json, composer.lock) ; Flutter lib/ n’est pas un projet Android/iOS autonome. Ne lancez pas Composer dans un dossier sans composer.json.
Séparer les environnements
Prévoir production, préproduction et développement avec domaines, bases, sauvegardes et identifiants distincts. Ne jamais connecter une application de test aux vrais moyens de paiement ni réutiliser la clé privée ÉDITEUR sur un CLIENT.
02
Checklist d’installation avant toute commande
Prévenir les erreurs de Composer, de permissions et de déploiement déjà rencontrées.
Confirmer les fichiers de base
Entrez dans le répertoire qui contient artisan ET composer.json ET composer.lock. Sur une archive cumulative seule, arrêtez-vous et récupérez le projet Laravel complet d’origine.
Exemple à adapter
cd /home/UTILISATEUR/mondomaine.com
pwd
for f in artisan composer.json composer.lock bootstrap/app.php; do test -f "$f" && echo "OK $f" || echo "ABSENT $f"; done
php -v; composer --version
Contrôler la compatibilité PHP
Laravel 13 exige PHP 8.3 ou une version supérieure supportée par les packages verrouillés. Vérifiez les extensions PHP réellement utilisées : pdo_mysql, cURL, DOM, Fileinfo, OpenSSL, Sodium, ZIP, Mbstring et XML. Le même binaire PHP doit être utilisé par Artisan et Composer.
La racine du domaine HTTPS doit être /home/UTILISATEUR/mondomaine.com/public. Vérifiez le certificat TLS, les permissions 755 pour les dossiers publics et 644 pour les fichiers ; storage et bootstrap/cache doivent être accessibles en écriture au service PHP.
Exemple à adapter
namei -l /home/UTILISATEUR/mondomaine.com/public/.htaccess
ls -ld public storage bootstrap/cache
Documenter les choix de déploiement
Avant la fusion, notez la branche/version sources, le rôle CLIENT ou ÉDITEUR, le nom du domaine canonique, le fournisseur d’hébergement, le chemin de sauvegarde privé et les moyens de paiement/notifications effectivement activés.
03
Avant de commencer
Identifiez la bonne livraison et préparez un environnement de travail.
Distinguer une installation et une mise à jour
Une installation neuve exige un projet Laravel complet avec artisan, composer.json, composer.lock et public/, ainsi qu’un projet Flutter complet avec pubspec.yaml, android/ et ios/. Une archive cumulative ou un dossier lib seul se fusionne avec le projet d’origine ; il ne remplace pas les fichiers de structure manquants.
Préparer les accès
Prévoyez un domaine HTTPS, un accès aux fichiers et au terminal de l’hébergement, une base de données dédiée et les sources complètes. Le serveur Laravel doit fonctionner avant de brancher l’application. Pour une mise en place soumise à licence, demandez aussi à l’éditeur l’adresse de sa centrale, sa clé publique et votre clé d’activation.
Choisir un environnement de test
Travaillez d’abord sur un sous-domaine et une base séparée. Pour un site déjà installé, passez directement au chapitre Mises à jour et sauvegardes.
04
Prérequis techniques
Vérifiez le serveur et les outils locaux avant d’installer les dépendances.
Serveur Laravel
Laravel 13 nécessite PHP 8.3 ou supérieur. Le fichier composer.lock et composer check-platform-reqs confirment les exigences exactes de la livraison. Vérifiez notamment cURL, DOM/XML, Fileinfo, Mbstring, OpenSSL et PDO avec le pilote de votre base. Le module de licence requiert aussi PHP Sodium.
Exemple à adapter
php -v
php -m
composer --version
Poste Flutter
Installez le SDK Flutter compatible avec les contraintes du pubspec.yaml, Git et les outils Android. Pour iOS, utilisez un Mac avec Xcode. Conservez le pubspec.lock et les fichiers Gradle de votre projet ; ne choisissez pas leurs versions au hasard.
Exemple à adapter
flutter --version
flutter doctor -v
05
Installer le serveur Laravel
Ce parcours concerne exclusivement une première installation sur une base vide.
1. Vérifier le projet complet et installer Composer
Ouvrez d'abord le projet Laravel complet d'origine, en local ou sur le serveur. Les archives cumulatives CLIENT/ÉDITEUR MutualBoost ne contiennent pas composer.json, composer.lock ni artisan : elles doivent être fusionnées avec le projet complet. Vérifiez ces trois fichiers AVANT Composer. Vous pouvez préparer les dépendances en local avec la bonne version de PHP, mais un vendor construit sous macOS ou Windows n'est pas garanti compatible avec le serveur Linux : privilégiez Composer sur o2switch ou une préparation sous Linux compatible. Sur le serveur, utilisez le même PHP pour Composer et Artisan.
Exemple à adapter
cd /home/UTILISATEUR/mondomaine.com
pwd
for f in artisan composer.json composer.lock bootstrap/app.php; do test -f "$f" || { echo "STOP: missing $f"; exit 1; }; done
php -v
composer install --no-dev --prefer-dist --optimize-autoloader
composer check-platform-reqs --no-dev
À retenir
Si Composer affiche « could not find a composer.json file », vous êtes dans le mauvais dossier ou n'avez que l'archive partielle. Ne faites pas composer init ni composer update : retrouvez le Laravel complet d'origine. Un dossier local est utile pour contrôler les fichiers, mais ne crée pas les fichiers manquants.
2. Configurer l’environnement
Créez .env à partir du modèle fourni uniquement si aucun fichier .env n’existe. Renseignez votre domaine et une base neuve. L’exemple ci-dessous contient des valeurs de remplacement ; il ne contient aucun identifiant de votre serveur.
Sur cette nouvelle installation uniquement, générez APP_KEY une fois, vérifiez la connexion à la base et appliquez les migrations. Gardez cette clé lors des mises à jour.
Sur un serveur existant, ne régénérez pas APP_KEY et ne lancez pas de commande qui recrée les tables.
4. Initialiser les données de la livraison
Sur une base neuve, le DatabaseSeeder fourni initialise les réglages et un jeu de démonstration. Il refuse une base déjà peuplée. Exécutez cette étape seulement si vous souhaitez cette initialisation.
Cette initialisation crée des données et des comptes fictifs. Ce n’est pas une procédure de mise à jour.
5. Régler le dossier Web et les fichiers
Le domaine doit servir le dossier public/ du projet. Autorisez PHP à écrire dans storage/ et bootstrap/cache/. Si public/storage est absent, créez le lien prévu. Si un vrai dossier existe déjà à cet emplacement, conservez-le et ses fichiers.
Exemple à adapter
if [ ! -e public/storage ] && [ ! -L public/storage ]; then
php artisan storage:link
fi
6. Ouvrir la plateforme et sécuriser le compte
Ouvrez /login. Dans la livraison actuelle, le seeder écrit les identifiants initiaux dans storage/app/mutualboost-demo-identifiants.txt, hors du dossier public. Consultez ce fichier uniquement sur votre serveur. Modifiez ensuite les coordonnées et le mot de passe de l’administrateur, puis configurez l’identité de votre mutuelle.
Exemple à adapter
php artisan config:clear
php artisan view:cache
06
Base de données, migrations et initialisation
Configurer MySQL sans effacer une installation existante.
Base neuve et identifiants dédiés
Créez une base MySQL et un utilisateur avec les privilèges strictement nécessaires. Conservez leurs identifiants dans .env hors public/ ; n’utilisez jamais la base d’un autre client.
Installez les dépendances issues de composer.lock puis validez le chargement Laravel. En cas d’erreur package:discover, diagnostiquez bootstrap/app.php et bootstrap/cache au lieu de relancer composer update.
Sur une base vide, exécutez migrate --force puis vérifiez migrate:status. Sur une base existante, sauvegardez d’abord : ne lancez jamais migrate:fresh, db:wipe ni un nettoyage manuel de la table migrations. Des migrations historiques peuvent avoir été archivées après consolidation.
DatabaseSeeder initialise les pages, paramètres et la démonstration sur une installation neuve. Il peut refuser une base peuplée ; ne le forcez pas en production. Le DemoMutualSeeder attend un contexte préparé par DatabaseSeeder et peut nécessiter Faker dans les dépendances installées.
Ne lancez pas DemoMutualSeeder isolément et ne publiez jamais des comptes de démonstration sur une vraie mutuelle.
Clé de chiffrement APP_KEY
Générez APP_KEY une seule fois pour une nouvelle installation. Elle protège les données chiffrées : toute régénération sur un site existant peut rendre les données antérieures illisibles.
Exemple à adapter
php artisan key:generate # NOUVELLE INSTALLATION UNIQUEMENT
07
Hébergement HTTPS, stockage et cron
Racine Web, fichiers, tâches planifiées et supervision.
Dossier public et lien de stockage
Le serveur doit servir public/index.php. Si public/storage n’existe pas, utilisez php artisan storage:link ; s’il est déjà un vrai répertoire contenant des fichiers, ne le supprimez pas sans inventaire et sauvegarde.
Exemple à adapter
cd /home/UTILISATEUR/mondomaine.com
if [ ! -e public/storage ] && [ ! -L public/storage ]; then php artisan storage:link; fi
Cron Laravel : une seule entrée par installation
Dans cPanel ou crontab, créez UNE tâche qui appelle schedule:run chaque minute avec le PHP de l’installation. schedule:list affiche les événements prévus mais ne prouve pas qu’un cron système est présent.
Contrôlez les rappels de cotisations, génération des dettes, rapprochement des paiements, expiration de contrats, notifications automatiques, rafraîchissement des licences et contrôle quotidien des versions. Les périodicités exactes doivent être lues dans schedule:list sur le serveur installé.
Si QUEUE_CONNECTION utilise database/redis, prévoyez un worker supervisé ou une méthode d’exécution compatible avec l’hébergement. Si votre installation utilise sync, aucune file asynchrone n’est démarrée ; vérifiez l’impact sur les notifications et les temps de réponse.
Exécuter un worker persistant uniquement si l’hébergement et la configuration le permettent.
HTTPS, sauvegardes et journaux
Activez TLS, redirection HTTP→HTTPS, APP_DEBUG=false, logs privés et sauvegardes base + fichiers. Testez périodiquement une restauration sur préproduction. Ne publiez jamais .env, storage/app/private, logs ou dumps SQL.
08
Administrateurs, droits et première connexion
Comptes initiaux, sécurité, rôles et parcours public.
Créer un compte administrateur autorisé
L’accès /login doit fonctionner même avant activation de licence afin que le véritable administrateur puisse rejoindre /admin/license. Pour l’installation de démonstration uniquement, DefaultAdminSeeder peut fournir un compte initial ; changez immédiatement son mot de passe et désactivez les accès de test avant la production.
Ne publiez pas les identifiants prédéfinis dans une page de documentation publique.
Rôles et capacités
Créez des rôles nommés (secrétariat, économe, responsable, gestionnaire) et attribuez les capacités strictement nécessaires. Réservez la licence, les clés de paiement, les mises à jour et l’administration des rôles au personnel habilité.
Navigation intelligente du site
Dans Administration → Site et application → Boutons Connexion/Inscription/Don, paramétrez les actions publiques. Le menu change selon Visiteur, Adhérent ou Administrateur ; les inscriptions doivent aussi respecter la politique d’ouverture et les restrictions de licence.
Désactiver les comptes démo
Les identifiants de la mutuelle fictive doivent être réservés aux environnements isolés. Vérifiez les droits, l’absence de fonctions financières réelles en mode démo et la déconnexion sécurisée via POST/CSRF.
09
Activer la licence de votre installation
Votre mutuelle utilise le rôle client. L’éditeur vous communique les informations de sa centrale.
1. Recevoir le bon dossier et les informations de licence
Votre installation réunit le projet Laravel complet, ses fichiers de mise à jour compatibles et, si vous avez l’application mobile, le projet Flutter complet. Recevez de l’éditeur l’URL HTTPS finale de sa centrale, sa clé publique et votre clé interne ou votre code d’achat CodeCanyon. Une archive cumulative ne remplace pas les fichiers de structure absents.
À retenir
Le rôle client correspond à la plateforme de votre mutuelle. Les adhérents utilisent ensuite votre site et votre application ; ils n’activent pas chacun une licence logicielle.
2. Configurer uniquement le rôle client
Dans le fichier .env du serveur Laravel de votre mutuelle, renseignez votre domaine et les informations publiques fournies par l’éditeur. L’exemple n’est pas une centrale déjà disponible. Après modification, videz le cache de configuration.
Après avoir enregistré .env, exécutez php artisan config:clear dans le terminal du projet Laravel. Le jeton auteur Envato et la clé privée de signature restent chez l’éditeur ; ils ne sont nécessaires ni sur votre serveur ni dans Flutter.
3. Saisir votre clé dans l’administration
Connectez-vous à /admin/license : Administration → Licence de la plateforme. Choisissez Licence interne MutualBoost si l’éditeur vous a remis une clé MBI, ou CodeCanyon / Envato si vous disposez d’un code d’achat. Saisissez-le et cliquez sur Activer la licence. Vérifiez ensuite le domaine et l’état Licence active. Un compte adhérent ou ADMIN-DEMO ne peut pas effectuer cette activation.
À retenir
Le code d’achat se trouve dans vos téléchargements Envato, avec le certificat de licence. Le mot de passe de votre compte Envato n’est pas demandé.
4. Vérifier le renouvellement et la continuité de service
Conservez le cron Laravel sur votre hébergement. Le serveur vérifie localement l’attestation pendant la navigation et tente son renouvellement lorsqu’elle atteint 24 heures. Une coupure temporaire laisse fonctionner l’attestation encore valide, jusqu’à sept jours et dans la limite d’une échéance interne. Vérifier maintenant permet de relancer le contrôle après résolution d’un problème.
La date de fin du support Envato est présentée séparément du droit d’utilisation. Le module ne transforme pas cette date de support en expiration de licence.
5. Transférer votre plateforme vers un autre domaine
Avant le transfert, ouvrez Transférer ou remplacer la licence dans /admin/license, confirmez la désactivation, puis activez sur le nouveau serveur et son domaine canonique. Gardez la même identité privée lors d’une simple mise à jour sur le même domaine. Si l’ancien serveur est inaccessible, demandez à l’éditeur de libérer l’installation.
À retenir
Ne copiez pas une installation activée pour ouvrir une deuxième plateforme. Le nombre de places dépend de votre licence ; un achat CodeCanyon est géré avec une installation active par produit final.
6. Comprendre une restriction et contacter l’assistance
Une attestation dépassée, une échéance interne ou une suspension peut interrompre les nouvelles écritures Web et API avec HTTP 423. La consultation, la récupération du compte, l’accès administrateur à la licence et les confirmations de paiements déjà initiés restent disponibles. Transmettez à l’éditeur le domaine, le message affiché et l’heure du problème, sans publier votre clé complète, .env ou vos mots de passe.
À retenir
Aucune centrale réelle ni aucun achat Envato ne sont activés par la simple lecture de ce guide. Les informations de raccordement viennent de votre éditeur.
10
Licences internes, Envato et activation CLIENT
Comprendre la durée, les attestations et les contrôles sans bloquer l’activation.
Activer directement depuis Laravel CLIENT
Dans /admin/license, un administrateur autorisé saisit la clé interne ou le code d’achat Envato. Le serveur contacte la centrale HTTPS, épingle sa clé publique lors du premier échange de confiance et vérifie l’attestation signée. Ne saisissez jamais la clé privée de signature dans l’interface CLIENT.
Une licence interne sans date de fin choisie est illimitée ; les droits d’usage Envato sont distincts du support. L’attestation technique a une durée limitée (jusqu’à sept jours) et est renouvelée périodiquement : cette date de renouvellement ne représente pas la date d’expiration commerciale.
Diagnostiquer sans exposer les secrets
Vérifiez le domaine APP_URL, l’empreinte publiée, la clé publique épinglée, le certificat et l’identité d’installation. Une empreinte n’est pas une clé publique complète. N’effacez pas client.json ou authority.json pour forcer une activation.
La suspension/révocation se pilote depuis la centrale et n’efface pas les opérations historiques. Pour changer réellement de domaine, préparez les sauvegardes et utilisez la libération/transfert de l’installation plutôt que de copier silencieusement un certificat sur un nouveau serveur.
11
Centre de mises à jour signées
Vérifier, sauvegarder, installer et restaurer sans prise de contrôle par le navigateur.
Installer le module d’updates une seule fois
La première intégration se fait par transfert fiable des sources, pas via une auto-mise à jour non encore installée. Vérifiez Sodium et ZIP. La clé publique d’updates est indépendante de la licence et doit être épinglée dans MUTUALBOOST_UPDATES_PUBLIC_KEY sur CLIENT.
La page /admin/updates affiche la version et les nouveautés. updates:check compare des manifestes signés. Un CLIENT actif peut télécharger via updates:download ; la signature Ed25519, la distribution ciblée et SHA-256 sont vérifiés avant copie.
L’installation des fichiers se lance uniquement avec une confirmation SSH et une version publiée. Sauvegardez base et fichiers. Pour les releases avec migration, fournissez le chemin du dump SQL, exécutez ensuite migrate --force, contrôlez les données et finalisez par updates:complete.
Exemple à adapter
php artisan updates:apply VERSION --confirm=VERSION --db-backup=/home/UTILISATEUR/sauvegardes/mondomaine-avant.sql
php artisan migrate --force # SI RELEASE AVEC MIGRATIONS
php artisan updates:complete --confirm=VERSION # SI MAINTENANCE EN ATTENTE
Récupération et limites du rollback
Si le code déployé échoue, utilisez updates:rollback --confirm=VERSION et vérifiez le service. Le rollback applicatif ne restaure NI les tables modifiées, NI les nouvelles dépendances Composer. Pour un retour arrière SQL, restaurez séparément une sauvegarde testée.
Cron de surveillance, pas d’installation silencieuse
updates:check est planifié quotidiennement dans routes/console.php. Le cron ne doit ni appeler updates:apply ni accepter un ZIP arbitraire fourni par formulaire Web. Conservez un journal de version, auteur, notes, contrôle SHA et restauration.
12
Hébergement et tâches automatiques
Préparez le domaine, le planificateur et, si nécessaire, les files de traitement.
cPanel et o2switch
Sélectionnez un PHP compatible pour le domaine et pour le terminal. Configurez la racine du domaine sur public/, activez HTTPS et créez la base ainsi que son utilisateur avec les droits adaptés. Si vous utilisez un chemin PHP particulier, remplacez php par ce chemin dans les commandes.
Planificateur Laravel
Ajoutez une seule entrée cron exécutée chaque minute. Remplacez les deux chemins de l’exemple. Consultez schedule:list pour vérifier que les tâches de la livraison sont effectivement enregistrées. Elles couvrent notamment le rapprochement des paiements, les échéances de contrats et les rappels.
Contrôle : php artisan schedule:list. Le fuseau horaire du projet détermine l’heure d’exécution des tâches.
Files de traitement
Si votre configuration utilise une file asynchrone, prévoyez un processus queue:work supervisé et relancé par votre hébergeur. Une configuration synchrone n’exige pas ce processus. Vérifiez le mode de votre livraison avant de l’activer.
13
OneSignal : notifications Android et iOS
Application OneSignal, FCM, APNs, secrets côté Laravel et réception Flutter.
Créer votre application OneSignal
Depuis le tableau de bord OneSignal, créez une application pour votre organisation. Dans Settings → Keys & IDs, récupérez App ID (UUID, partageable avec le SDK) et REST API Key (SECRET, serveur uniquement). Utilisez des identifiants distincts entre test et production.
Configurer Android et Firebase Cloud Messaging
Dans Firebase Console, créez/associez le projet Android avec le package exact de l’application, activez FCM et configurez les identifiants de service demandés par OneSignal. Ajoutez google-services.json seulement selon la configuration native prévue par le projet ; ne copiez jamais une clé de serveur dans Flutter.
Configurer Apple Push Notification service
Dans Apple Developer, utilisez le bon Bundle ID, activez Push Notifications et fournissez à OneSignal une clé APNs ou le certificat conforme à sa procédure. Configurez les capacités Xcode Push Notifications et Background Modes/Remote notifications si requises et testez sur un véritable iPhone.
Brancher Laravel et protéger la REST API Key
Dans Administration → Paramètres généraux → API / Notifications, renseignez onesignal_app_id, onesignal_rest_api_key et activez onesignal_enabled seulement après validation. Laravel rejette les valeurs fictives ; un champ secret laissé vide ne doit pas écraser l’ancien secret. La clé REST ne doit jamais être rendue dans le HTML public ou dans l’API Flutter.
Initialiser le SDK Flutter et l’utilisateur
Conservez la dépendance onesignal_flutter du pubspec.yaml, initialisez le SDK avec l’App ID (non secret), demandez les permissions au moment approprié et associez l’utilisateur connecté à l’identifiant externe attendu par Laravel. À la déconnexion, dissociez l’identité conformément au SDK installé.
Exemple à adapter
// Schéma d’intégration : adapter à la version onesignal_flutter du projet
// OneSignal.initialize("APP_ID_UUID");
// OneSignal.login("IDENTIFIANT_UTILISATEUR_LARAVEL");
Tester chaque chemin de notification
Tester sur deux appareils : permission, token/abonnement, message direct, cible utilisateur, rappel cotisation, ouverture profonde et déconnexion. Les contrôleurs Laravel fournis contiennent encore des appels OneSignal historiques (api/v1 + include_external_user_ids) ; vérifiez leur compatibilité avec les API OneSignal actuelles avant de considérer les pushes comme opérationnels.
Publiez les règles de confidentialité et collectez les consentements nécessaires. Ne transmettez pas de diagnostics médicaux ou détails financiers sensibles en texte de notification sur l’écran verrouillé. Vérifiez la déclaration de confidentialité des magasins mobiles.
14
Email SMTP, SMS et modèles de messages
Configurer les fournisseurs réels, les expéditeurs et les scénarios métier.
Email : SMTP opérationnel
Dans Paramètres généraux, section API, renseignez smtp_host, smtp_port, smtp_username, smtp_password, smtp_encryption, smtp_from_address et smtp_from_name. Le serveur doit pouvoir joindre ce port sortant. Vérifiez SPF/DKIM/DMARC chez votre fournisseur et envoyez un message test.
SMS : choisir le fournisseur
Le sélecteur prévu contient Twilio, Infobip, Orange SMS API ou un fournisseur personnalisé. Saisissez sms_provider, sms_api_key, sms_api_secret et sms_sender_id selon votre contrat ; testez la livraison vers un numéro autorisé avant d’activer des relances massives.
Personnaliser les événements
Activez par événement welcome, payment, approval, rejection, new_dependent, death_notice ou reminder les canaux notify_*_email, notify_*_sms et notify_*_push. Ajustez objets, textes et titres, puis testez une vraie exécution sur un compte de test.
Surveiller les incidents
Consultez les logs Laravel, les éventuels jobs en échec, les quotas fournisseurs, les refus d’authentification et les erreurs HTTP. N’enregistrez pas les REST API Keys en clair dans des rapports partagés.
15
Paiements : activation et rapprochement
Paramétrer les opérateurs sans confondre présentation commerciale et authentification API.
Choisir les intégrations disponibles
Le code comprend des réglages pour Wave, CinetPay, TouchPay, PayPal et Flutterwave ; d’autres paramètres FedaPay, Jeko et Stripe existent selon le parcours. Activez uniquement le fournisseur réellement raccordé à son API et à son contrat marchand.
Saisir les clés dans l’administration
Dans Paramètres généraux → Paiements, renseignez les identifiants adaptés : Wave API key/signing secret ; CinetPay Site ID/API key/secret ; TouchPay codes d’agence et authentification ; PayPal Client ID/secret/environnement ; Flutterwave secret. Les logos, noms publics et ordre d’affichage n’affectent pas les identifiants techniques.
Retours, webhooks et double paiement
Configurez les URLs de retour, annulation et webhook selon les routes réellement présentes et le tableau de bord opérateur. Validez côté serveur la signature/référence, le montant, la devise, le statut et l’idempotence ; ne considérez jamais le simple retour navigateur comme preuve de paiement.
Faire des essais complets en sandbox
Vérifiez paiements réussis, échoués, annulés, différés, webhooks répétés, pertes réseau et rapprochement payments:reconcile-pending. Inspectez les journaux sans publier numéros de carte, secrets ou données de santé.
Commencez quand le serveur HTTPS et ses API sont disponibles.
1. Ouvrir le projet complet
Ouvrez le dossier contenant pubspec.yaml. Un correctif lib doit être fusionné dans ce projet. Installez les dépendances et examinez les diagnostics avant de compiler.
Exemple à adapter
flutter pub get
flutter analyze
2. Renseigner le serveur de votre mutuelle
Dans les sources Flutter vérifiées, lib/services/api_service.dart définit baseUrl et storageUrl. Remplacez ces deux adresses par celles de votre serveur. Conservez /api pour l’API et /storage/ pour les fichiers publics. Une version différente peut centraliser ces valeurs ailleurs : recherchez leurs définitions.
Flutter se connecte à votre plateforme cliente. Ne remplacez pas baseUrl par l’adresse de la centrale de licences.
3. Régler l’identité de l’application
Vérifiez le nom affiché, les icônes, l’identifiant Android et le Bundle Identifier iOS dans les projets natifs fournis. Utilisez vos propres identifiants pour une nouvelle application. Les identifiants d’une application déjà publiée doivent être conservés.
4. Tester sur un appareil
Détectez votre appareil ou émulateur puis lancez l’application. Vérifiez l’accueil, la connexion, les médias, les langues et une consultation des cotisations avec des données de test.
Exemple à adapter
flutter devices
flutter run
À retenir
Le téléphone doit pouvoir joindre le domaine HTTPS. localhost depuis un téléphone désigne ce téléphone, pas votre ordinateur.
17
Flutter : projet complet, API et identité
Brancher les sources Dart au serveur Laravel et préserver les variantes de styles.
Rassembler le projet mobile complet
Travaillez avec le dépôt Flutter complet comprenant pubspec.yaml, pubspec.lock, lib/, android/, ios/ et les assets. Le ZIP lib/ cumulatif ne suffit pas pour compiler des binaires ; faites une sauvegarde et fusionnez ensuite la nouvelle lib/ dans le vrai projet.
Configurer les URLs de votre serveur
Utilisez les paramètres de compilation effectivement reconnus par le projet MutualBoost ; ne laissez pas une URL de démo codée en dur. Le domaine API et l’URL des médias doivent pointer vers la même instance CLIENT HTTPS.
Exemple à adapter
flutter pub get
flutter run --dart-define=MUTUALBOOST_API_BASE_URL=https://mondomaine.com/api --dart-define=MUTUALBOOST_STORAGE_URL=https://mondomaine.com/storage/
Connexion, rôle et licence partagés
Les jetons d’authentification, rôles et permissions proviennent de Laravel. Une activation effectuée dans /admin/license déverrouille site et application selon les droits. Flutter doit afficher les états de licence sans jamais intégrer les clés privées ou une validation cryptographique qui contournerait Laravel.
Cinq styles et messages d’état
Conservez les cinq modèles visuels et leurs couleurs dynamiques. Le bandeau de messages d’état se place juste sous chaque AppBar, défile horizontalement, interprète une ligne comme un message et disparaît si aucun message n’est défini. Les couleurs du texte/fond dépendent du statut et sont pilotées par Laravel.
Tester l’intégration complète
Sur un appareil Android et un iPhone, testez login, inscription autorisée, adhérent, rôles, licence inactive/active, notifications, affichage des médias, paiements sandbox, traduction et changement de style. Réexécutez flutter analyze après toute fusion.
Exemple à adapter
flutter doctor -v
flutter analyze
flutter test
18
Compiler et publier Android
Préparez la signature de production avant de distribuer votre application.
Signature et configuration
Configurez votre clé de signature dans le projet Android selon la procédure Flutter officielle. Conservez une sauvegarde privée de cette clé et de ses mots de passe. Vérifiez aussi la version de l’application, les permissions et les réglages de notifications.
Générer les fichiers de diffusion
L’AAB sert à la publication Google Play ; l’APK permet des tests de distribution directe. Les sorties habituelles sont build/app/outputs/bundle/release/ et build/app/outputs/flutter-apk/. Testez le fichier release avant publication.
La compilation ne publie pas automatiquement l’application. Téléversez ensuite l’AAB dans votre propre compte Google Play Console et complétez sa fiche.
19
Compiler et publier iOS
La distribution iOS se prépare sur macOS avec le projet Xcode fourni.
Préparer Xcode et la signature
Ouvrez ios/Runner.xcworkspace lorsque le workspace est présent. Sélectionnez votre équipe Apple, le bon Bundle Identifier et les profils de signature. Si le projet utilise CocoaPods et que les dépendances le demandent, lancez pod install depuis ios/. Un compte Apple Developer est nécessaire pour distribuer sur l’App Store.
Créer une archive de distribution
Générez l’archive signée puis vérifiez le résultat dans build/ios/. Testez avec TestFlight avant l’envoi en validation.
Exemple à adapter
flutter build ipa --release
À retenir
Le certificat, les profils et la configuration de votre compte Apple restent nécessaires ; cette commande ne garantit pas à elle seule l’acceptation sur l’App Store.
20
Publication Android, iOS et confidentialité
Préparer builds de production, signature, magasins et versionnage.
Android et Play Console
Vérifiez applicationId/package, versionCode/versionName, keystore, configuration Firebase/FCM, permissions et icônes. Compilez un AAB signé, distribuez-le d’abord en test interne, testez liens profonds, notifications et achats/paiements selon votre distribution.
Sur macOS, configurez Bundle Identifier, équipe Apple, signature, APNs et les capacités requises. Compilez pour iOS/TestFlight, validez la notification sur appareil physique et renseignez les métadonnées, l’assistance et la politique de confidentialité avant soumission.
La centrale signe et livre les mises à jour de code Laravel, mais pas les applications installées depuis les stores. Publiez chaque nouvelle version Flutter dans Google Play et App Store ; ne promettez pas de mise à jour native automatique par le système PHP.
Liens universels et confidentialité
Configurez assetlinks.json et apple-app-site-association avec le domaine et les identifiants d’application réels lorsqu’un lien profond est prévu. Tenez à jour les déclarations de collecte de données, permissions système et consentements liés à OneSignal, Firebase et aux services tiers.
21
Paramètres de la mutuelle et gestion quotidienne
Cotisations, produits, dépenses, rôles, adhérents et dossiers.
Identité et paramètres généraux
Après activation, modifiez coordonnées, WhatsApp, téléphone, adresse, horaires, conditions d’adhésion, délai de carence, pénalités, dates de cotisation et messages publics dans l’administration CLIENT.
Gérer les adhérents et ayants droit
Vérifiez les formulaires dynamiques d’inscription, profils, adhérents, assurés et ayants droit. Définissez les documents requis, les validations et les permissions ; testez un compte adhérent du dépôt jusqu’à l’approbation.
Trésorerie, dettes et dépenses
La gestion des cotisations, règlements, prêts, produits, demandes, budgets et dépenses dépend des rôles, des états de paiement et des règles de la mutuelle. Contrôlez les totaux avant diffusion d’un état financier. Les commandes automatisées peuvent générer des dettes ou expirer des contrats.
Documents privés et conformité
Protégez les pièces justificatives et documents dynamiques : les téléchargements sensibles doivent passer par une autorisation utilisateur, pas par un lien public. Prévoyez durées de conservation, demandes de suppression et sauvegardes chiffrées.
Offres, dons et bandeau d’état
Activez la visibilité du bouton Don si la mutuelle le souhaite. Définissez les offres et leur présentation, puis renseignez les messages par état (visiteur, à jour, non à jour, en attente) avec couleurs fond/texte ; une liste vide masque le bandeau dans Flutter.
22
Apparences, langues et contenu de vitrine
Harmoniser les cinq styles, traductions et contenus Web/mobile.
Choisir le style actif
Le Studio et les écrans d’apparence gèrent les cinq styles responsive. Choisissez la palette, les images, les composants de page et les règles d’affichage ; validez sur ordinateur, tablette et téléphone. Ne confondez pas la vitrine commerciale et la démonstration d’une mutuelle fictive.
Langues et contenus dynamiques
Le module de langues permet activation, ordre, traduction de libellés et traductions de contenus. Testez au minimum français/anglais et les autres langues activées, ainsi que l’affichage RTL lorsque l’arabe est utilisé. Un champ non traduit peut utiliser le contenu par défaut ; contrôlez visuellement ces replis.
Vitrine et SEO
Configurez les services, les avantages, les FAQ, le référencement, les images réelles et les liens Google Play/App Store. Les captures d’écran doivent correspondre aux fonctionnalités livrées ; évitez les URLs temporaires et les données personnelles réelles dans la démonstration.
Navigation et pages publiques
Validez les boutons Connexion, Inscription et Don, les liens personnalisés HTTPS, les pages légales et les écrans d’état de licence. La consultation de la vitrine reste possible si une licence doit être vérifiée, sans autoriser les écritures métier.
23
Configurer le site et l’application
Les réglages publiés depuis Laravel pilotent les interfaces prévues par la livraison.
Démarrer depuis l’un des cinq modèles
Dans Administration → Démarrer depuis un modèle, préparez l’identité, les contacts et les pages, puis enregistrez l’aperçu privé. Vérifiez-le avant de publier. La publication active le portail réel et désactive les démonstrations Web et mobile.
Choisir le bon studio
Dans Site et application, utilisez Apparence et styles pour la charte, Studio pages Web pour les pages du site, Studio pages Flutter pour les pages natives et Widgets accueil et adhérents pour leurs emplacements. Sélectionnez le style réellement publié et la bonne page avant d’enregistrer.
Configurer les langues
Activez les langues dans Langues et traductions. Traductions des contenus permet d’adapter les textes éditoriaux, les articles et les libellés métier. Testez le site et l’application dans chaque langue activée. Le nom légal de la mutuelle reste une identité propre.
Organiser les inscriptions et les droits
Dans Administration → Inscription et paiement, choisissez le format du formulaire, les étapes, le choix simple ou multiple de produits et le paiement demandé avant validation. Dans Rôles et capacités puis Affectation des rôles, attribuez les droits et contrôlez le résultat avec un compte du rôle concerné.
24
Paiements, notifications et téléchargements
Connectez les services externes à partir des réglages du backend.
Configurer les paiements
Ouvrez Cotisations et trésorerie → Passerelles de paiement et les réglages de paiement utilisés par votre circuit. Renseignez les comptes marchands, l’environnement et les URL de notification exigées par le prestataire. Personnalisez les noms, logos et l’ordre des agrégateurs. Vérifiez un paiement et sa confirmation serveur avant l’ouverture au public.
Exemple à adapter
php artisan route:list --path=payment
À retenir
Une page de retour réussie ne suffit pas à confirmer un encaissement. Les secrets marchands restent sur le serveur.
Configurer email, SMS et notifications Push
Dans Administration → Email, SMS et notifications, renseignez les services réellement utilisés. Vérifiez les modèles et destinataires avec un compte de test. Pour OneSignal, configurez également les capacités et paramètres propres aux projets Android et iOS de votre livraison.
Afficher les liens des stores
Dans Site et application → Téléchargements de l’application, enregistrez les liens HTTPS officiels Google Play et App Store. Chaque bouton s’affiche quand son lien valide existe. Pour le portail publié, activez aussi la section Application et téléchargements dans le projet de plateforme.
25
Mises à jour et sauvegardes
Ce parcours préserve une installation existante et ses données.
Avant toute mise à jour
Sauvegardez la base de données, les fichiers téléversés, .env et les sources de la version en service. Gardez la sauvegarde hors du dossier public. Vérifiez la restauration dans un environnement séparé et lisez la notice de la livraison.
Installer la mise à jour
Fusionnez uniquement les fichiers de la livraison dans le projet complet, en conservant .env, APP_KEY et les téléversements. Exécutez le script indiqué dans sa notice. Si composer.lock change, réinstallez les dépendances verrouillées. Appliquez des migrations uniquement lorsqu’elles sont prévues par cette mise à jour. Ne relancez pas les seeders d’initialisation.
Contrôler puis rouvrir
Videz les caches concernés et recompilez les vues, puis vérifiez connexion, droits, paiements et documents. Un worker asynchrone doit être redémarré après modification de son code. Pour Flutter, fusionnez les sources compatibles, testez et générez une nouvelle version native si le code client a changé.
Conservez les fichiers de la version précédente. Une restauration de base doit être coordonnée avec les écritures et paiements intervenus depuis la sauvegarde. Ne restaurez pas une base ancienne par-dessus des opérations récentes sans rapprochement.
26
Sécurité, journalisation et sauvegardes
Limiter les accès, protéger les secrets et valider les restaurations.
Ne pas exposer les secrets
Conservez .env, APP_KEY, clés privées de licences, clés de signatures d’updates, API keys et identifiants DB hors public/. Restreignez les permissions SSH et activez MFA chez les fournisseurs qui le permettent. Masquez les secrets lors des demandes d’assistance.
Sauvegardes 3-2-1 et restauration testée
Sauvegardez régulièrement base, pièces jointes, storage/app/private, .env et certificats/clefs. Stockez une copie hors serveur, chiffrez les copies et contrôlez l’intégrité. Exécutez au moins une restauration sur un serveur de préproduction.
Surveiller vulnérabilités et journaux
Contrôlez composer audit, les versions des packages, journaux Laravel et tâches en erreur. Une correction Composer impliquant composer.lock doit être testée hors du système automatique de ZIP applicatifs. Ne déployez pas une mise à jour sans compatibilité confirmée.
Testez lecture/écriture pour visiteur, adhérent, gestionnaire et administrateur, notamment en licence suspendue. Les confirmations de paiement vérifiées côté serveur et l’accès administratif à la licence peuvent rester disponibles suivant la politique implémentée.
27
Dépannage et réponses aux incidents
Procédures reproductibles et sûres sans effacer les données.
Composer ne trouve pas composer.json
Cela signifie que le dossier courant n’est pas le projet Laravel complet. Recherchez composer.json, artisan et bootstrap/app.php, puis déplacez-vous dans le bon dossier. Ne créez pas un faux composer.json pour contourner l’erreur.
Vérifiez la chaîne de répertoires avec namei -l, l’appartenance des fichiers, le dossier public comme racine du domaine et les journaux Apache de l’hébergeur. N’appliquez pas chmod 777 en masse.
Exemple à adapter
namei -l /home/UTILISATEUR/mondomaine.com/public/.htaccess
ls -la public/.htaccess
Licence refusée / attestation invalide
Vérifiez APP_URL canonique, connexion HTTPS à la centrale, clé publique épinglée, empreinte et état d’installation avec licenses:diagnose. Ne régénérez pas les clés de signature pour tenter un dépannage.
Vérifiez App ID réel, secret API côté Laravel, configuration FCM/APNs, permissions, abonnement du terminal, External ID et logs HTTP. Vérifiez aussi les anciens endpoints api/v1 du code présent avant de passer en production.
Mise à jour interrompue / base en décalage
En cas d’échec, conservez l’état du journal privé, le dump SQL et les archives précédentes. Ne sortez pas de maintenance si des migrations sont en attente ; relancez les contrôles puis terminez ou restaurez explicitement.
Vérifiez les --dart-define, les caches de domaine, la version du lib/ réellement compilée, les cinq styles et le statut renvoyé par l’API. Effectuez flutter clean uniquement si nécessaire et ne supprimez pas pubspec.lock sans diagnostic.
28
Dépannage rapide
Commencez par le symptôme et vérifiez les points indiqués.
Composer introuvable ou composer.json absent
Exemple o2switch : cd ~/mondomaine.com puis pwd et find . -maxdepth 3 -name composer.json -print. Si aucun fichier n'apparaît, le dossier contient seulement une livraison partielle, pas le Laravel complet. Récupérez le projet d'origine : artisan, composer.json, composer.lock, bootstrap/ et public/. Ne lancez ni composer init, ni migrate:fresh. Installer Composer en local ne résout pas l'absence des fichiers source.
Exemple à adapter
pwd
find . -maxdepth 3 -name composer.json -print
Erreur 500 ou page blanche
Consultez storage/logs/laravel.log sur le serveur, vérifiez PHP et ses extensions, les droits d’écriture et la connexion à la base. Gardez APP_DEBUG=false en production. Ne publiez pas le contenu complet des journaux ou de .env.
Page, CSS, JavaScript ou image en 404
Vérifiez la racine public/ du domaine, la présence du fichier et sa casse. Une image téléversée doit correspondre au stockage configuré. Conservez un public/storage déjà existant ; réparez le chemin concerné après sauvegarde. Les outils VERIFIER_ASSETS_VITRINE.sh et VERIFIER_VUES_COMPILEES.php sont fournis dans les livraisons qui les incluent.
Erreur de base ou seeder refusé
Vérifiez les coordonnées de .env et migrate:status. Un refus du DatabaseSeeder sur une base peuplée protège l’installation : utilisez la procédure de mise à jour. N’effacez pas les données pour contourner ce refus.
Style, widget ou bouton de store absent
Vérifiez le style publié, la page ou l’emplacement sélectionné, l’activation du bloc et ses traductions. Rechargez les réglages de l’application. Pour les stores, enregistrez une URL officielle valide et activez la section correspondante du portail.
Compilation Flutter, Gradle ou iOS en échec
Examinez flutter doctor -v et le premier message d’erreur utile. Vérifiez la compatibilité du SDK, du JDK et des fichiers Gradle fournis ; sur iOS, la signature et les dépendances natives. Ne remplacez pas des numéros de version au hasard.
L’application ne joint pas le serveur
Vérifiez baseUrl, le suffixe /api, HTTPS, le réseau de l’appareil et l’accessibilité de l’API. Une erreur 401 indique généralement un besoin de connexion ; une erreur 403 peut correspondre aux droits du compte. Ne contournez pas ces contrôles.
LARAVEL + FLUTTER
Références officielles
Références techniques complémentaires. Les noms de commandes et les chemins réellement installés font foi. Aucun secret de connexion ne doit être copié dans cette documentation publique.
Référence basée sur les entrées du menu d’administration Laravel. Certaines entrées sont conditionnées par les permissions, le type de licence ou la configuration ; les fonctions doivent être testées sur votre installation.
Pilotage1 rubriques
Tableau de bord
Consulter les indicateurs de pilotage, les activités récentes et les alertes disponibles.
Accès nécessaire : reports.view
Membres et dossiers6 rubriques
Adhésions
Examiner les demandes d’adhésion, vérifier les pièces et traiter les dossiers.
Accès nécessaire : users.view
Membres principaux
Consulter, rechercher et gérer les membres principaux selon les droits accordés.
Accès nécessaire : users.view
Assurés rattachés
Rattacher et gérer les personnes assurées liées aux membres.
Accès nécessaire : assures.view
Ayants droit
Gérer les ayants droit et leurs liens avec les dossiers.
Accès nécessaire : beneficiaries.view
Formulaires dynamiques
Concevoir les formulaires adaptés aux parcours de la mutuelle.
Accès nécessaire : settings.manage
Champs personnalisés
Ajouter les informations personnalisées nécessaires aux dossiers.
Accès nécessaire : settings.manage
Cotisations et trésorerie12 rubriques
Tontines et cycles
Ouvrir la rubrique « Tontines et cycles » et gérer ses éléments selon les permissions du compte.
L'Avantage Mobile : Une gestion financière instantanée
La gouvernance mutualiste entre dans une nouvelle ère. Votre application personnalisée Gbama MutualBoost permet à chaque membre de régler ses cotisations en qu…
Digitalisation des Mutuelles : La fin des registres manuels et des impayés
La gestion manuelle des cotisations représente le risque financier majeur des mutuelles modernes. Avec la technologie MutualBoost, l'automatisation prend le re…
Taux d'engagement maximal grâce aux Notifications Push
Détenir une application native sur le téléphone de vos adhérents est l'outil de communication ultime pour un bureau exécutif.Relances et alertes imparablesFini…