Aller au contenu

Module Création de compte

Objectif

Le module Création de compte est un parcours d'inscription artisan séparé de l'application PHP historique.

Il couvre :

  • une interface React/Vite en deux etapes ;
  • une API Node/Express dédiée à l'inscription ;
  • la création d'un membre Solutravo ;
  • la création de la presociete artisan rattachée au membre ;
  • la notification email administrateur ;
  • la trace et le retry des notifications admin ;
  • la generation d'un jeton d'autologin ;
  • la redirection vers l'application Solutravo après inscription ;
  • les workflows de déploiement du frontend et du backend d'inscription.

Emplacement du code

Le module a été identifié sur les branches register/prod et register/staging.

Arborescence principale :

backend/
  app.ts
  server.ts
  src/controllers/RegisterController.ts
  src/services/RegisterService.ts
  src/services/AutoLoginTokenService.ts
  src/services/RegistrationRedirect.ts
  src/jobs/retryAdminRegistrationNotifications.ts
  src/config/env.ts
  src/config/db.ts
  src/routes/router.ts
frontend/
  src/pages/Inscription.tsx
  src/pages/Inscription.css
  src/helpers/fetchData.ts
.github/workflows/deploy-backend.yml
.github/workflows/deploy-frontend.yml

Point important : ce module n'est pas une page ajoutée dans app/views de l'application PHP. C'est une petite application autonome qui écrit dans la même base métier Solutravo.

Vue d'ensemble architecture

Navigateur
  |
  | POST /api/register
  v
Backend inscription Node/Express
  |
  | transaction SQL
  v
Base Solutravo
  - membres
  - presocietes
  - registration_admin_notifications
  |
  | SMTP
  v
Email administrateur

Backend inscription
  |
  | redirectUrl + token JWT court
  v
Application Solutravo
  - /connexion-microservice?token=...

Frontend

Fichier principal :

  • frontend/src/pages/Inscription.tsx

Le formulaire est decoupe en deux etapes :

  1. Connexion : email et mot de passe.
  2. Societe : nom, prénom, entreprise, taille d'entreprise, téléphone.

Validation visible côté frontend :

  • téléphone français au format 0612345678, +33612345678 ou 0033612345678 ;
  • champs requis par etape ;
  • affichage d'une erreur API sous le formulaire ;
  • modal de succès après réponse positive.

Le frontend appelle :

POST {VITE_API_BASE_URL}/register

via frontend/src/helpers/fetchData.ts.

La variable VITE_API_BASE_URL est obligatoire au démarrage du frontend. Le helper lève une erreur si elle est absente, ce qui évite de construire une URL silencieusement invalide.

Redirection après inscription

Le frontend privilégie le redirectUrl retourné par le backend. Si un autoLoginToken est présent, il force la route d'autologin :

/connexion-microservice?token=...

Sinon, il retombe sur :

/connexion?email=...

La normalisation d'origin remplace notamment :

  • auth.staging.solutravo-compta.fr par staging.solutravo-compta.fr ;
  • frontend.staging.solutravo-compta.fr par staging.solutravo-compta.fr ;
  • auth.solutravo-app.fr par app.solutravo-app.fr.

Cette logique existe aussi côté backend. En cas de reprise, maintenir les deux implémentations cohérentes, ou centraliser le contrat pour éviter une divergence.

Backend

Point d'entrée HTTP :

  • backend/src/routes/router.ts
  • backend/src/controllers/RegisterController.ts

Route exposee :

POST /api/register

Payload attendu :

{
  "nom": "Durand",
  "prénom": "Alice",
  "email": "alice@example.com",
  "phonenumber": "0612345678",
  "name": "Entreprise Durand",
  "size": "2 a 5 personnes",
  "passe": "Motdépassé1"
}

Réponse de succès :

{
  "success": true,
  "message": "Inscription réussie, notification administrateur envoyée",
  "data": {
    "email": "alice@example.com",
    "adminNotificationSent": true,
    "adminNotificationId": 1,
    "autoLoginTokenCreated": true,
    "autoLoginToken": "...",
    "redirectUrl": "https://.../connexion-microservice?token=..."
  }
}

Règles métier d'inscription

Fichier :

  • backend/src/services/RegisterService.ts

Validations backend :

  • email obligatoire et valide ;
  • prénom obligatoire ;
  • nom obligatoire ;
  • nom d'entreprise obligatoire ;
  • téléphone obligatoire ;
  • mot de passe obligatoire ;
  • mot de passe fort : au moins 8 caractères, 1 majuscule, 1 chiffre ;
  • téléphone français normalisé avant validation ;
  • email unique dans membres.

Ecritures SQL dans une transaction :

  1. vérification d'absence de membre existant avec le même email ;
  2. hash du mot de passe avec bcrypt.hash(passe, 10) ;
  3. insertion dans membres avec :
  4. type = 'membre' ;
  5. statut = 'actif' ;
  6. isVerified = 0 ;
  7. email_verification_required_at renseigné à l'heure courante UTC ;
  8. ref = UUID() ;
  9. insertion dans presocietes avec :
  10. role = 'artisan' ;
  11. membre_id rattaché au membre créé ;
  12. nom, taille et téléphone de l'entreprise.

La transaction est commitée après les deux insertions. En cas d'erreur, elle est rollbackée.

Codes d'erreur métier utilisés :

  • 400 pour email ou champs obligatoires invalides ;
  • 409 quand l'email existe déjà ;
  • 422 pour mot de passe trop faible ou téléphone invalide.

Notification administrateur

Le module envoie un email admin après création du compte.

Variables impliquées :

SMTP_HOST
SMTP_PORT
SMTP_USER
SMTP_PASSWORD
SMTP_SECURE
REGISTER_EMAIL_SENDER
REGISTER_EMAIL_SENDER_NAME
REGISTER_EMAIL_REPLY_TO
REGISTER_EMAIL_LOGO_URL
REGISTER_ADMIN_NOTIFICATION_EMAIL
REGISTER_ADMIN_NOTIFICATION_SUBJECT
REGISTER_ADMIN_NOTIFICATION_MAX_ATTEMPTS
REGISTER_ADMIN_NOTIFICATION_RETRY_DELAY_MINUTES
REGISTER_ADMIN_NOTIFICATION_RETRY_LIMIT

Avant l'envoi, le service crée une trace en base dans registration_admin_notifications.

Table créée automatiquement par le service si elle n'existe pas :

registration_admin_notifications
  id
  membre_id
  email
  recipient_email
  status
  attempt_count
  payload_json
  last_error
  next_retry_at
  sent_at
  created_at
  updated_at

Statuts :

  • pending
  • sent
  • failed

Si l'email admin échoue, l'inscription reste valide. La réponse API indique adminNotificationSent: false et garde l'identifiant de notification quand il existe.

Retry des notifications admin

Fichier :

  • backend/src/jobs/retryAdminRegistrationNotifications.ts

Le job :

  1. charge l'environnement ;
  2. lit REGISTER_ADMIN_NOTIFICATION_RETRY_LIMIT, avec 20 par défaut ;
  3. sélectionne les notifications pending ou failed dont next_retry_at est vide ou dépassé ;
  4. ignore les lignes ayant atteint REGISTER_ADMIN_NOTIFICATION_MAX_ATTEMPTS, avec 5 par défaut ;
  5. renvoie l'email ;
  6. marque la trace en sent ou failed.

Le délai de retry est exponentiel à partir de REGISTER_ADMIN_NOTIFICATION_RETRY_DELAY_MINUTES, avec 15 minutes par défaut et un multiplicateur plafonné.

Autologin

Fichier :

  • backend/src/services/AutoLoginTokenService.ts

Le backend génère un JWT HS256 avec :

{
  "userId": 123,
  "email": "alice@example.com"
}

TTL par défaut :

REGISTER_AUTOLOGIN_TOKEN_TTL_SECONDS=600

Secret utilisé par ordre de priorité :

  1. REGISTER_AUTOLOGIN_JWT_SECRET
  2. API_SECRET_KEY
  3. secret de secours code dans la branche

Point de reprise important : en production, ne jamais dépendre du secret de secours. Définir explicitement REGISTER_AUTOLOGIN_JWT_SECRET et vérifier que l'application Solutravo qui consomme /connexion-microservice utilise le même secret et le même algorithme.

CORS et exposition HTTP

Fichier :

  • backend/app.ts

Le backend expose :

  • GET / pour une réponse de statut API ;
  • GET /health ;
  • POST /api/register.

Origins autorisées par défaut :

http://localhost:5173
http://127.0.0.1:5173
https://auth.staging.solutravo-compta.fr
https://auth.solutravo-app.fr

La variable CORS_ALLOWED_ORIGINS remplace cette liste si elle est renseignée.

Headers autorisés :

  • Content-Type
  • Authorization
  • Origin
  • Accept
  • X-Requested-With

Chargement d'environnement

Fichier :

  • backend/src/config/env.ts

Le backend cherche un .env dans cet ordre :

  1. répertoire courant du process ;
  2. deux niveaux au-dessus du répertoire de base ;
  3. trois niveaux au-dessus du répertoire de base.

Si aucun fichier n'est trouvé, dotenv.config() est appelé sans chemin explicite.

Cette logique existe pour supporter à la fois le dev local, le build dist/ et le déploiement où le .env est écrit dans le dossier déployé.

Déploiement

Workflows :

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

Branches declencheuses :

  • register/staging
  • register/prod

Backend :

  • Node 20.19.4 ;
  • pnpm 10.33.0 ;
  • build dans backend/ ;
  • copie de package.json dans backend/dist/ ;
  • création du .env depuis les variables GitHub ;
  • déploiement SSH vers un VPS ;
  • restart PM2 avec --update-env.

Frontend :

  • Node 20.19.4 ;
  • pnpm 10.33.0 ;
  • build dans frontend/ ;
  • injection de VITE_API_BASE_URL selon la branche ;
  • déploiement FTP du dossier frontend/dist/.

URLs API configurées dans le workflow frontend :

register/prod    -> https://backend.auth.solutravo-app.fr/api
register/staging -> https://backend.auth.solutravo-compta.fr/api

Tests identifiés

Fichiers :

  • backend/tests/registrationRedirect.test.ts
  • backend/tests/env.test.ts

La couverture existante vérifie surtout :

  • la construction de l'URL de redirection ;
  • la priorité du token d'autologin sur l'email ;
  • le fallback si REGISTER_SUCCESS_REDIRECT_URL est absent ou invalide ;
  • la resolution des chemins .env.

Il n'y a pas, dans les fichiers identifiés, de test d'intégration couvrant une inscription complète avec base MySQL, insertion membres, insertion presocietes et création de la trace de notification.

Points d'attention pour reprise

  • Le module écrit directement dans les tables métier Solutravo. Toute évolution du schéma membres ou presocietes doit être répercutée ici.
  • La table registration_admin_notifications est créée au runtime par le service. Pour une exploitation stricte, prévoir une migration SQL versionnée plutôt que de laisser la création implicite au premier envoi.
  • L'inscription est considérée réussie même si la notification admin échoue. C'est volontaire dans le code actuel, mais le monitoring du job de retry devient indispensable.
  • Le secret d'autologin doit être géré par variable d'environnement et partagé avec l'application qui valide le token.
  • La logique de normalisation des URLs existe côté frontend et côté backend. Toute modification de domaine doit être faite aux deux endroits ou factorisée.
  • Le backend retourne actuellement le token au frontend dans la réponse JSON. Il faut conserver un TTL court et servir uniquement en HTTPS.
  • Le helper frontend reconstruit les erreurs et ne conserve pas le status HTTP d'origine dans l'erreur relancée. Pour du debug support, il peut être utile de préserver ce status.
  • Les commentaires et libellés du helper frontend ne sont pas totalement homogènes. Ne pas les prendre comme documentation contractuelle ; le contrat fiable est le couple POST /api/register et la réponse du contrôleur.