👤 Customers Management

📋 Vue d'ensemble

Le module Customers Management gère les clients du système. Il fait partie du grand module Actors et fournit des fonctionnalités CRUD complètes pour la gestion des profils clients avec validation des données et gestion des relations.

🏗️ Architecture

• Queue NATS : admin-service
• Patterns : customers.*
• Sécurité : bcrypt avec salt rounds (10)
• Validation : class-validator pour tous les DTOs
• Relations : Utilisateur, pays, état

📡 Message Patterns NATS

1. Lister les Clients

Pattern : customers.all

Payload (CustomerQueryDto)

{
  "page": 1,
  "limit": 10,
  "countryId": 15,
  "stateId": 106,
  "status": "ACTIVE",
  "gender": "MALE",
  "search": "john.doe",
  "sortBy": "createdAt",
  "sortOrder": "desc"
}

Filtres Disponibles

• page (optionnel): Numéro de page (défaut: 1)
• limit (optionnel): Nombre d'éléments par page (défaut: 10)
• countryId (optionnel): Filtrer par pays
• stateId (optionnel): Filtrer par état/région
• status (optionnel): Statut du client (ACTIVE, INACTIVE, SUSPENDED, BLOCKED)
• gender (optionnel): Genre (MALE, FEMALE)
• search (optionnel): Recherche dans firstName, lastName, email

2. Détails d'un Client

Pattern : customers.details

Payload

{
  "id": "customer-uuid"
}

Réponse inclut

• Informations client complètes
• Utilisateur associé
• Pays et état
• Statistiques de transports
• Historique des activités

3. Créer un Client

Pattern : customers.create

Payload (CreateCustomerDto)

{
  "lastName": "Doe",
  "firstName": "John",
  "email": "john.doe@customer.com",
  "phone": "+1234567890",
  "password": "securePassword123",
  "countryId": 15,
  "stateId": 106,
  "gender": "MALE",
  "dateOfBirth": "1990-01-01"
}

Logique de Création

1. Vérification d'unicité : Vérifie que l'email n'existe ni dans users ni dans customers
2. Hachage du mot de passe : Utilise bcrypt avec un salt de 10
3. Génération du username : {firstName} {LASTNAME} (ex: "John DOE")
4. Transaction : Crée l'utilisateur puis le client en une seule transaction
5. Valeurs par défaut :
   • status: ACTIVE
   • roleId: 1 (rôle client)
   • Dates de vérification automatiquement définies

Réponse de Succès

{
  "success": true,
  "message": "Customer created successfully",
  "result": {
    "id": 1,
    "publicId": "customer-uuid",
    "lastName": "Doe",
    "firstName": "John",
    "email": "john.doe@customer.com",
    "phone": "+1234567890",
    "userId": 1,
    "countryId": 15,
    "stateId": 106,
    "gender": "MALE",
    "dateOfBirth": "1990-01-01T00:00:00.000Z",
    "status": "ACTIVE",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "user": {
      "id": 1,
      "publicId": "user-uuid",
      "username": "John DOE",
      "email": "john.doe@customer.com",
      "status": "ACTIVE"
    },
    "country": {
      "id": 15,
      "name": "Bénin"
    },
    "state": {
      "id": 106,
      "name": "Atlantique"
    }
  }
}

4. Mettre à jour un Client

Pattern : customers.update

Payload (UpdateCustomerDto)

{
  "id": "customer-uuid",
  "updateData": {
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+0987654321",
    "gender": "FEMALE"
  }
}

5. Supprimer un Client

Pattern : customers.delete

Payload

{
  "id": "customer-uuid"
}

Note : Suppression logique si le client a des transports ou plaintes associés.

6. Changer le Statut d'un Client

Pattern : customers.change-status

Payload

{
  "id": "customer-uuid",
  "statusData": {
    "status": "SUSPENDED",
    "reason": "Activité suspecte détectée"
  }
}

7. Statistiques des Clients

Pattern : customers.stats

Réponse

{
  "success": true,
  "message": "Customer statistics retrieved successfully",
  "result": {
    "totalCustomers": 500,
    "activeCustomers": 450,
    "inactiveCustomers": 30,
    "suspendedCustomers": 20,
    "customersByCountry": [
      {"countryId": 15, "countryName": "Bénin", "count": 250},
      {"countryId": 16, "countryName": "Nigeria", "count": 250}
    ],
    "customersByGender": [
      {"gender": "MALE", "count": 300},
      {"gender": "FEMALE", "count": 200}
    ],
    "customersThisMonth": 45,
    "topCustomers": [
      {
        "id": 1,
        "publicId": "customer-uuid",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@customer.com",
        "transportsCount": 25,
        "totalSpent": 50000.00
      }
    ],
    "recentCustomers": [
      {
        "id": 1,
        "publicId": "customer-uuid",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@customer.com",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

📊 Enums et Statuts

Statuts Client (CustomerStatus)

enum CustomerStatus {
    ACTIVE = 'ACTIVE',         // Actif
    INACTIVE = 'INACTIVE',     // Inactif
    SUSPENDED = 'SUSPENDED',   // Suspendu
    BLOCKED = 'BLOCKED'        // Bloqué
}

Genre (Gender)

enum Gender {
    MALE = 'MALE',         // Masculin
    FEMALE = 'FEMALE'      // Féminin
}

🚀 Fonctionnalités Avancées

1. Validation des Données

• Contraintes métier : Vérification des règles business
• Validation des emails : Format et unicité
• Validation des téléphones : Format international
• Intégrité référentielle : Cohérence des relations

2. Gestion des Statuts

• Changement de statut : Avec raison obligatoire
• Historique des statuts : Traçabilité complète
• Notifications automatiques : Alertes sur changements
• Règles métier : Validation des transitions

3. Recherche et Filtrage

• Recherche multi-critères : Nom, email, téléphone
• Filtres avancés : Par pays, état, genre, statut
• Tri personnalisé : Par différents champs
• Pagination : Performance optimisée

💡 Exemples d'Utilisation

Créer un Client Standard

{
  "lastName": "Doe",
  "firstName": "Jane",
  "email": "jane.doe@example.com",
  "phone": "+229987654321",
  "password": "SecurePass123!",
  "countryId": 15,
  "stateId": 106,
  "gender": "FEMALE",
  "dateOfBirth": "1985-03-15"
}

Rechercher des Clients par Genre

{
  "page": 1,
  "limit": 20,
  "gender": "FEMALE",
  "countryId": 15,
  "status": "ACTIVE",
  "sortBy": "createdAt",
  "sortOrder": "desc"
}

Suspendre un Client Problématique

{
  "id": "customer-problem-001",
  "statusData": {
    "status": "SUSPENDED",
    "reason": "Comportement abusif signalé par plusieurs agents"
  }
}

---

🎯 Le module Customers Management offre une gestion complète des clients avec validation des données, gestion des statuts et recherche avancée pour optimiser la relation client et assurer la qualité du service.