L’inscription capture une intention : une personne demande à utiliser le produit. La création opérationnelle confirme quelque chose de plus exigeant : une organisation peut accéder au produit, possède la configuration minimale valide, ses responsables disposent des autorisations nécessaires et les ressources requises existent de manière cohérente. Traiter ces deux moments comme une unique requête HTTP crée souvent des comptes incomplets, des délais d’attente, des doublons et des procédures manuelles difficiles à auditer.
Le provisionnement de comptes SaaS en PHP doit être conçu comme un processus métier récupérable. Cela implique de conserver son état, d’exécuter le travail en arrière-plan, de tolérer les répétitions et de fournir aux opérations suffisamment de contexte pour agir sans modifier directement les enregistrements en production.
Définir quand une organisation est réellement prête
Avant de décider des tables, des événements ou des files, il convient de fixer un contrat de préparation. Une organisation ne devrait pas être marquée comme active parce qu’une ligne a été insérée dans la base de données. Elle doit respecter des critères vérifiables qui dépendent du produit.
- Identité et accès : l’organisation existe, l’utilisateur initial a été créé ou invité et possède le rôle administratif prévu.
- Configuration de base : le fuseau horaire, la langue, la politique d’accès, le plan ou les limites ont été résolus avec des valeurs explicites.
- Données initiales : les ressources indispensables ont été créées, telles que des espaces de travail, des catalogues vides, des règles ou des préférences.
- Dépendances externes : lorsqu’elles sont nécessaires, des ressources telles qu’un tenant chez un fournisseur, un abonnement ou un identifiant technique ont été demandées ou vérifiées.
- Responsabilité : il est clair qui peut terminer les étapes en attente et quelle action est activée pour cette personne.
Séparer les exigences obligatoires des améliorations facultatives évite de bloquer l’accès à cause de tâches qui ne sont pas critiques. Par exemple, générer un import d’exemple peut être facultatif ; valider une politique de sécurité requise ne l’est pas. Cette distinction empêche également l’équipe de transformer chaque préférence commerciale en une variante permanente du produit.
Modéliser la création comme une machine à états
Une machine à états rend visibles les transitions autorisées et réduit l’ambiguïté d’un champ générique tel que active. Un modèle initial peut inclure requested, provisioning, ready, blocked, failed et cancelled. Les noms exacts importent moins que les règles.
Par exemple, une demande valide crée l’organisation dans l’état requested. Un orchestrateur la fait passer à provisioning et planifie des tâches. Seul un contrôle de préparation peut la faire passer à ready. Une erreur non récupérable, telle qu’une contrainte contractuelle ou des données invalides, peut la faire passer à blocked ; un échec technique après épuisement des tentatives peut rester dans l’état failed, toujours avec une raison structurée.
Enregistrez chaque transition avec la date, l’acteur, la cause et la corrélation. L’acteur peut être un utilisateur, un processus ou un opérateur. N’autorisez pas de changements arbitraires depuis les contrôleurs ni depuis les scripts d’administration : centralisez les transitions dans un service de domaine et validez l’état d’origine. Cela évite, par exemple, de réactiver une organisation annulée par le biais d’une tentative tardive.
Séparer la requête du travail lent
La requête d’inscription devrait valider les données, appliquer une clé d’idempotence, persister la demande et renvoyer une réponse rapide. La création de ressources, qui peut être lente, l’appel à des API tierces, l’envoi d’e-mails ou le chargement des données de base doivent être traités par des tâches asynchrones.
En PHP, un worker de file d’attente peut exécuter de petites tâches observables : créer l’administrateur, appliquer le template de configuration, provisionner une intégration ou vérifier la préparation. Il ne convient pas de déléguer toute la logique à un unique job opaque : s’il échoue, il sera difficile de savoir ce qui a été terminé et ce qui peut être relancé. Un template définit des valeurs initiales réutilisables ; il ne doit pas être confondu avec un modèle de données ni avec une copie isolée de l’application pour chaque client.
Idempotence et traçabilité dans les tâches de provisionnement
Les réseaux échouent, les navigateurs renvoient des formulaires et les workers peuvent traiter le même message plus d’une fois. L’idempotence garantit que répéter une opération produit le même effet logique, et non qu’elle ne s’exécute jamais deux fois.
Attribuez une idempotency_key à la demande de création et stockez-la avec le périmètre approprié, normalement le canal et l’organisation demandée. Imposez une contrainte unique pour l’identité métier concernée, telle que le domaine vérifié ou un identifiant externe. Pour les ressources dérivées, utilisez des clés stables : créer l’espace default pour une organisation doit le retrouver s’il existe déjà, et non en insérer un autre.
provisioning_task - organization_id - task_type - input_payload - status - attempt_count - result_payload - error_code - error_detail - correlation_id - started_at - finished_at
Le input_payload permet de reconstruire ce qui a été demandé ; le résultat enregistre des identifiants externes ou des ressources créées. Conservez error_code stable et utile pour l’automatisation, tandis que le détail peut contenir un contexte technique protégé. La correlation_id doit circuler de la demande aux logs, aux événements et aux appels sortants afin d’examiner une création complète sans relier manuellement les indices.
Un worker doit réclamer la tâche de manière sûre, enregistrer la tentative et confirmer le résultat uniquement après l’avoir persisté. Si une API externe accepte une clé d’idempotence, utilisez une clé dérivée de la tâche, et non une clé aléatoire à chaque tentative. Si elle ne l’accepte pas, recherchez la ressource distante au moyen d’un identifiant déterministe avant de la créer.
Récupérer les échecs partiels sans les masquer
Toutes les erreurs ne requièrent pas la même réponse. Relancez de manière limitée les échecs transitoires, tels qu’une indisponibilité temporaire, des limites de débit ou des conflits de concurrence. Appliquez un délai d’attente croissant et une limite de tentatives ; relancer sans contrôle augmente la charge et peut multiplier les effets externes.
Ne compensez que lorsque la réversion est sûre et qu’elle apporte une valeur. Supprimer une organisation partiellement créée peut être correct avant d’accorder l’accès, mais peut être risqué si elle contient déjà une activité du client. Dans de nombreux cas, il est préférable de bloquer l’activation, de conserver les éléments de preuve et de soumettre le cas à examen.
- Relancer : dépendance temporairement indisponible et opération idempotente.
- Compenser : la ressource créée n’a pas d’utilisation ultérieure et peut être supprimée sans perdre la traçabilité.
- Bloquer : une condition obligatoire manque, telle qu’une validation ou une acceptation requise.
- Examiner : il existe une divergence entre l’état local et un fournisseur externe, ou les tentatives ont été épuisées.
Une console opérationnelle minimale doit afficher l’organisation, l’état actuel, les tâches, les tentatives, la dernière erreur, la corrélation et les actions autorisées : relancer une tâche, reprendre le flux, annuler ou signaler une exception avec un motif. Les actions doivent générer une piste d’audit. Donner un accès direct à la base de données comme procédure habituelle élimine les contrôles et rend impossible la distinction entre une correction et une modification accidentelle.
Configuration initiale maintenable et tests du flux
Utilisez une configuration déclarative versionnée pour les valeurs de base par segment de produit, plan ou région. Appliquez des règles explicites et limitées, plutôt que de brancher le code selon le client. Une véritable exception doit rester une capacité configurable avec un propriétaire, une date de révision et un effet connu ; sinon, chaque création accumulera des conditions impossibles à retirer.
Les tests doivent couvrir davantage que le formulaire. Vérifiez les transitions valides et invalides, la répétition de la même demande, l’exécution dupliquée d’un job, deux demandes concurrentes pour la même identité et la reprise après un échec. Testez également la compensation lorsqu’elle existe et l’impossibilité d’activer une organisation sans préconditions. Pour les intégrations externes, utilisez des doublures de test qui reproduisent des réponses lentes, des erreurs et des résultats déjà créés.
Mesurez le temps entre la demande et la préparation, la proportion de créations nécessitant une intervention, les nouvelles tentatives par type de tâche, les échecs terminaux et le temps passé dans chaque état. Segmentez par version du flux, origine et type de compte afin de détecter une régression précise. Une hausse des inscriptions terminées accompagnée d’une augmentation des organisations bloquées n’est pas une amélioration de l’onboarding : elle n’a fait que déplacer la friction.
Liste de contrôle pour examiner le processus actuel
- Existe-t-il une définition partagée et vérifiable d’une organisation prête ?
- Les transitions sont-elles restreintes et auditées ?
- La réponse HTTP ne dépend-elle pas de tâches lentes ou de fournisseurs externes ?
- Chaque demande et tâche possède-t-elle une clé idempotente et une corrélation traçable ?
- Les nouvelles tentatives distinguent-elles les erreurs transitoires des erreurs métier ?
- Les opérations peuvent-elles diagnostiquer et reprendre une création sans modifier directement les données ?
- Les configurations initiales sont-elles déclaratives, versionnées et limitées ?
- Les tests couvrent-ils les doublons, la concurrence et les échecs partiels ?
Lorsque ces réponses sont affirmatives, la création cesse d’être un formulaire fragile et devient une capacité opérationnelle du SaaS : observable, récupérable et prête à évoluer sans transférer sa complexité au client ni à l’équipe de support.
