Système d'Authentification et Comptes Clients

Ce document décrit le système d'authentification de l'application e-commerce, incluant l'inscription, la connexion, la gestion du profil utilisateur et l'intégration avec le système de fidélité.

Vue d'ensemble

Le système d'authentification gère l'ensemble du cycle de vie des comptes clients :

Inscription avec création de compte fidélité
Connexion avec génération de token JWT
Synchronisation automatique avec l'API Fidélité
Gestion du profil utilisateur (coordonnées, points, niveau)
Autocomplete d'adresse via l'API gouvernementale française

Composants impliqués

Frontend :
- AuthContext.tsx : Contexte React pour l'authentification
- AuthPage.tsx : Page d'inscription et connexion
- AddressAutocomplete.tsx : Composant de recherche d'adresse
- AccountPage.tsx : Page de profil utilisateur
Backend :
- auth.service.ts : Logique d'authentification et synchronisation
- auth.controller.ts : Endpoints REST
- fidelite.service.ts : Intégration avec l'API Fidélité
Base de données : Table users avec synchronisation fidélité

Endpoints API

Inscription d'un nouveau client

POST /api/auth/register

Crée un nouveau compte client et génère automatiquement un compte fidélité associé.

Body :

{
  "email": "jean.dupont@example.com",
  "motDePasse": "motdepasse123",
  "prenom": "Jean",
  "nom": "Dupont",
  "telephone": "0612345678",
  "adresse": "123 Rue de la Paix, 75001 Paris"
}

Champs :

email (requis) : Email unique du client
motDePasse (requis) : Mot de passe (min. 6 caractères)
prenom (requis) : Prénom du client
nom (requis) : Nom du client
telephone (optionnel) : Numéro de téléphone
adresse (optionnel) : Adresse complète

Réponse :

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 42,
  "email": "jean.dupont@example.com",
  "prenom": "Jean",
  "nom": "Dupont",
  "clientId": "CLI_A3B5C7D9",
  "pointsFidelite": 0,
  "niveauFidelisation": "Standard",
  "telephone": "0612345678",
  "adresse": "123 Rue de la Paix, 75001 Paris"
}

Format du clientId : CLI_XXXXXXXX où X est un caractère hexadécimal (8 caractères).

Codes de réponse :

201 Created : Compte créé avec succès
409 Conflict : Email déjà utilisé
400 Bad Request : Données invalides

Connexion

POST /api/auth/login

Authentifie un client existant et retourne un token d'accès.

Body :

{
  "email": "jean.dupont@example.com",
  "motDePasse": "motdepasse123"
}

Réponse :

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 42,
  "email": "jean.dupont@example.com",
  "prenom": "Jean",
  "nom": "Dupont",
  "clientId": "CLI_A3B5C7D9",
  "pointsFidelite": 150,
  "niveauFidelisation": "Bronze",
  "telephone": "0612345678",
  "adresse": "123 Rue de la Paix, 75001 Paris"
}

Codes de réponse :

200 OK : Connexion réussie
401 Unauthorized : Email ou mot de passe incorrect

Récupérer le profil utilisateur

GET /api/auth/me

Récupère le profil complet de l'utilisateur connecté avec synchronisation automatique des données fidélité.

Headers :

Authorization: Bearer <accessToken>

Réponse :

{
  "id": 42,
  "email": "jean.dupont@example.com",
  "prenom": "Jean",
  "nom": "Dupont",
  "clientId": "CLI_A3B5C7D9",
  "pointsFidelite": 150,
  "niveauFidelisation": "Bronze",
  "telephone": "0612345678",
  "adresse": "123 Rue de la Paix, 75001 Paris",
  "createdAt": "2024-11-13T10:30:00Z",
  "updatedAt": "2024-11-13T15:45:00Z",
  "derniereSynchro": "2024-11-13T15:45:00Z"
}

Synchronisation automatique

À chaque appel de /api/auth/me, le système synchronise automatiquement les points de fidélité et le niveau de fidélisation depuis l'API Fidélité. Les coordonnées (téléphone, adresse) ne sont jamais écrasées lors de la synchronisation.

Codes de réponse :

200 OK : Profil retourné
401 Unauthorized : Token invalide ou expiré

Déconnexion

POST /api/auth/logout

Révoque le token d'authentification de l'utilisateur.

Headers :

Authorization: Bearer <accessToken>

Réponse :

{
  "message": "Déconnexion réussie"
}

Codes de réponse :

200 OK : Déconnexion réussie
401 Unauthorized : Token invalide

Intégration avec le système de Fidélité

Création de compte fidélité

Lors de l'inscription, le système tente automatiquement de créer un compte dans l'API Fidélité :

Recherche : Vérification si un compte existe déjà pour l'email
Création : Si aucun compte n'existe, création avec prenom, nom, email
Fallback : En cas d'échec de l'API Fidélité, génération d'un clientId local

Format du clientId généré :

Via API Fidélité : Format fourni par l'API (ex: CLI_12345678)
En fallback local : CLI_XXXXXXXX (8 caractères hexadécimaux aléatoires)

Synchronisation des données

Le système synchronise uniquement les données suivantes depuis l'API Fidélité :

✅ Points de fidélité (pointsFidelite)
✅ Niveau de fidélisation (niveauFidelisation)
✅ Prénom et nom (si modifiés dans Fidélité)

Données NON synchronisées :

❌ Téléphone (géré uniquement par le formulaire d'inscription)
❌ Adresse (gérée uniquement par le formulaire d'inscription)

Gestion des coordonnées

Les coordonnées de contact (téléphone et adresse) sont exclusivement gérées par l'application e-commerce et ne sont jamais écrasées par les données de l'API Fidélité, car celle-ci ne les gère pas de manière fiable.

Fonctionnalités Frontend

Autocomplete d'adresse

Le composant AddressAutocomplete permet une saisie facilitée de l'adresse en utilisant l'API gouvernementale française.

API utilisée : https://api-adresse.data.gouv.fr/search/

Fonctionnement :

L'utilisateur tape une adresse (ex: "123 rue de la paix paris")
Après 300ms de pause (debounce), une requête est envoyée à l'API
Les suggestions apparaissent sous forme de liste déroulante
Au clic sur une suggestion, les champs sont pré-remplis

Données extraites :

rue : Numéro et nom de la rue (ex: "123 Rue de la Paix")
codePostal : Code postal (ex: "75001")
ville : Nom de la ville (ex: "Paris")

Adresse finale : Concaténation au format {rue}, {codePostal} {ville}

Pré-remplissage au Checkout

Lorsqu'un utilisateur connecté accède à la page de paiement (/checkout), ses coordonnées sont automatiquement pré-remplies :

Prénom et nom
Email
Téléphone (si renseigné)
Adresse parsée en rue, code postal et ville (si renseignée)

Parsing de l'adresse : Le système utilise une expression régulière pour extraire le code postal de l'adresse complète :

const codePostalMatch = adresse.match(/\b(\d{5})\b/);

Gestion des tokens

Génération

Les tokens JWT sont générés avec les informations suivantes :

userId : ID de l'utilisateur
email : Email de l'utilisateur
Durée de validité : 7 jours

Stockage

Backend : Table auth_tokens avec date d'expiration
Frontend : localStorage via le contexte React

Validation

À chaque requête protégée, le AuthGuard vérifie :

Présence du token dans l'en-tête Authorization: Bearer <token>
Existence du token en base de données
Date d'expiration non dépassée
Existence de l'utilisateur associé

Révocation

Lors de la déconnexion, le token est supprimé de la base de données et du localStorage.

Schéma de la table `users`

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  mot_de_passe_hash VARCHAR(255),
  prenom VARCHAR(100),
  nom VARCHAR(100),
  telephone VARCHAR(50),
  adresse TEXT,
  client_id VARCHAR(50) UNIQUE,
  points_fidelite INTEGER DEFAULT 0,
  niveau_fidelisation VARCHAR(50) DEFAULT 'Standard',
  derniere_synchro TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Champs clés :

client_id : Identifiant unique du compte fidélité (format CLI_XXXXXXXX)
points_fidelite : Points de fidélité synchronisés depuis l'API
niveau_fidelisation : Niveau de fidélité (Standard, Bronze, Silver, Gold, etc.)
derniere_synchro : Date de la dernière synchronisation avec l'API Fidélité

Flux d'inscription

Flux de connexion

Bonnes pratiques d'intégration

Pour les équipes frontend

Toujours utiliser le contexte AuthContext pour accéder aux données utilisateur
Vérifier isAuthenticated avant d'afficher du contenu protégé
Gérer les erreurs 401 en redirigeant vers la page de connexion
Utiliser le composant AddressAutocomplete pour toute saisie d'adresse
Ne pas stocker de données sensibles dans le localStorage (le token suffit)

Pour les équipes backend

Utiliser le AuthGuard sur tous les endpoints nécessitant une authentification
Accéder à l'utilisateur via req.user dans les contrôleurs protégés
Ne jamais écraser telephone/adresse lors des synchronisations Fidélité
Logger les tentatives de connexion pour le monitoring de sécurité
Gérer gracieusement les échecs de l'API Fidélité (fallback sur clientId local)

Pour l'équipe Fidélité

Ce que vous devez fournir :

Endpoint de recherche client par email : GET /api/publique/clients?email={email}
Endpoint de création client : POST /api/publique/clients
Endpoint de récupération client : GET /api/publique/clients/{clientId}
Format de clientId cohérent (recommandé : CLI_XXXXXXXX)

Ce que nous synchronisons depuis votre API :

Points de fidélité (pointsFidelite)
Niveau de fidélisation (niveauFidelisation)
Prénom et nom (en cas de mise à jour)

Ce que nous ne synchronisons PAS :

Téléphone (géré par notre formulaire d'inscription)
Adresse (gérée par notre formulaire d'inscription)

Surveillance et logs

Logs disponibles

Le système génère des logs détaillés pour chaque opération :

Inscription :

[AuthService] 🔍 SERVICE - Données destructurées:
   - telephoneInput: "0612345678" (type: string)
   - adresseInput: "123 Rue de la Paix, 75001 Paris" (type: string)
[AuthService] Tentative d'inscription pour email: jean.dupont@example.com
[FideliteService] ❌ Client jean.dupont@example.com non trouvé dans Fidélité
[FideliteService] Création du client dans l'API Fidélité...
[AuthService] ✅ Synchronisation Fidélité réussie:
   - ClientID: CLI_A3B5C7D9
[AuthService] ✨ Nouveau compte créé avec succès: jean.dupont@example.com (ID: 42)

Connexion :

[AuthService] Tentative de connexion pour email: jean.dupont@example.com
[AuthService] ✅ Connexion réussie pour: jean.dupont@example.com (ID: 42)

Synchronisation :

[AuthService] 🔄 Synchronisation du profil utilisateur 42...
[FideliteService] 🔍 Récupération du client CLI_A3B5C7D9
[AuthService] ✅ Profil utilisateur 42 synchronisé avec succès
   - Points: 150
   - Niveau: Bronze

Métriques à surveiller

Taux de succès des inscriptions
Taux d'échec de l'API Fidélité (pour activer le fallback local)
Durée de synchronisation des profils
Nombre de tokens expirés/révoqués

Liens utiles

Swagger Backend : https://e-commerce.staging.ubsi.fr/api/swagger
API Adresse Gouvernementale : https://api-adresse.data.gouv.fr
Documentation API Fidélité : [À compléter par l'équipe Fidélité]

Vue d'ensemble​

Composants impliqués​

Endpoints API​

Inscription d'un nouveau client​

Connexion​

Récupérer le profil utilisateur​

Déconnexion​

Intégration avec le système de Fidélité​

Création de compte fidélité​

Synchronisation des données​

Fonctionnalités Frontend​

Autocomplete d'adresse​

Pré-remplissage au Checkout​

Gestion des tokens​

Génération​

Stockage​

Validation​

Révocation​

Schéma de la table users​

Flux d'inscription​

Flux de connexion​

Bonnes pratiques d'intégration​

Pour les équipes frontend​

Pour les équipes backend​

Pour l'équipe Fidélité​

Surveillance et logs​

Logs disponibles​

Métriques à surveiller​

Liens utiles​

Vue d'ensemble

Composants impliqués

Endpoints API

Inscription d'un nouveau client

Connexion

Récupérer le profil utilisateur

Déconnexion

Intégration avec le système de Fidélité

Création de compte fidélité

Synchronisation des données

Fonctionnalités Frontend

Autocomplete d'adresse

Pré-remplissage au Checkout

Gestion des tokens

Génération

Stockage

Validation

Révocation

Schéma de la table `users`

Flux d'inscription

Flux de connexion

Bonnes pratiques d'intégration

Pour les équipes frontend

Pour les équipes backend

Pour l'équipe Fidélité

Surveillance et logs

Logs disponibles

Métriques à surveiller

Liens utiles