🚛 Agents Management

📋 Vue d'ensemble

Le module Agents Management gère les agents du système (FOCAL_POINT et AGENT). Il fait partie du grand module Actors et suit la même logique que les admins pour créer un compte utilisateur et un profil agent associé, avec génération automatique de code agent et gestion des affectations aux localités.

🏗️ Architecture

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

📡 Message Patterns NATS

1. Lister les Agents

Pattern : agents.list

Payload (AgentQueryDto)

{
  "page": 1,
  "limit": 10,
  "type": "FOCAL_POINT",
  "countryId": 15,
  "stateId": 106,
  "status": "ACTIVE",
  "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)
• type (optionnel): Type d'agent (FOCAL_POINT, AGENT)
• countryId (optionnel): Filtrer par pays
• stateId (optionnel): Filtrer par état/région
• status (optionnel): Statut de l'agent (ACTIVE, INACTIVE)
• search (optionnel): Recherche dans firstName, lastName, email, code

2. Détails d'un Agent

Pattern : agents.details

Payload

{
  "id": "agent-uuid"
}

Réponse inclut

• Informations agent complètes
• Utilisateur associé
• Pays et état
• Localités affectées
• Statistiques de performance

3. Créer un Agent

Pattern : agents.create

Payload (CreateAgentDto)

{
  "lastName": "Doe",
  "firstName": "John",
  "email": "john.doe@agent.com",
  "phone": "+1234567890",
  "password": "securePassword123",
  "countryId": 15,
  "stateId": 106,
  "type": "FOCAL_POINT",
  "localityIds": ["locality-uuid-1", "locality-uuid-2"]
}

Logique de Création

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

Réponse de Succès

{
  "success": true,
  "message": "Agent created successfully",
  "result": {
    "id": 1,
    "publicId": "agent-uuid",
    "lastName": "Doe",
    "firstName": "John",
    "email": "john.doe@agent.com",
    "phone": "+1234567890",
    "userId": 1,
    "countryId": 15,
    "stateId": 106,
    "code": "BJ-FP-001",
    "type": "FOCAL_POINT",
    "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@agent.com",
      "status": "ACTIVE"
    },
    "country": {
      "id": 15,
      "name": "Bénin"
    },
    "state": {
      "id": 106,
      "name": "Atlantique"
    }
  }
}

4. Mettre à jour un Agent

Pattern : agents.update

Payload (UpdateAgentDto)

{
  "id": "agent-uuid",
  "updateData": {
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+0987654321",
    "type": "AGENT"
  }
}

5. Supprimer un Agent

Pattern : agents.delete

Payload

{
  "id": "agent-uuid"
}

Note : Suppression logique si l'agent a des activités associées.

6. Affecter un Agent à une Localité

Pattern : agents.assign-locality

Payload

{
  "agentId": "agent-uuid",
  "localityId": "locality-uuid",
  "isPrimary": true
}

7. Affecter un Agent à Plusieurs Localités

Pattern : agents.assign-localities

Payload

{
  "agentId": "agent-uuid",
  "localityIds": ["locality-uuid-1", "locality-uuid-2"],
  "isPrimary": false
}

8. Statistiques des Agents

Pattern : agents.stats

Réponse

{
  "success": true,
  "message": "Agent statistics retrieved successfully",
  "result": {
    "totalAgents": 50,
    "activeAgents": 45,
    "focalPoints": 15,
    "regularAgents": 35,
    "agentsByCountry": [
      {"countryId": 15, "countryName": "Bénin", "count": 30},
      {"countryId": 16, "countryName": "Nigeria", "count": 20}
    ],
    "agentsByStatus": [
      {"status": "ACTIVE", "count": 45},
      {"status": "INACTIVE", "count": 5}
    ],
    "recentAgents": [
      {
        "id": 1,
        "publicId": "agent-uuid",
        "firstName": "John",
        "lastName": "Doe",
        "code": "BJ-FP-001",
        "type": "FOCAL_POINT",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

📊 Enums et Statuts

Types d'Agents (AgentType)

enum AgentType {
    FOCAL_POINT = 'FOCAL_POINT',   // Point focal (superviseur)
    AGENT = 'AGENT'                // Agent standard
}

Statuts d'Agent (AgentStatus)

enum AgentStatus {
    ACTIVE = 'ACTIVE',         // Actif
    INACTIVE = 'INACTIVE'      // Inactif
}

Génération du Code Agent

Format : {ISO_PAYS}-{TYPE_ABREGE}-{NUMERO}

• ISO_PAYS : Code ISO du pays (ex: BJ, NG)
• TYPE_ABREGE :
  • FP pour FOCAL_POINT
  • AG pour AGENT
• NUMERO : Numéro séquentiel sur 3 chiffres (ex: 001, 002)

Exemples

• BJ-FP-001 : Premier point focal du Bénin
• NG-AG-025 : 25ème agent du Nigeria

🚀 Fonctionnalités Avancées

1. Gestion des Localités

• Affectation multiple : Un agent peut couvrir plusieurs localités
• Localité principale : Désignation de la zone prioritaire
• Hiérarchie : Points focaux supervisent les agents
• Couverture géographique : Optimisation territoriale

2. Génération Automatique de Code

• Format standardisé : Cohérence dans tout le système
• Unicité garantie : Pas de doublons possibles
• Traçabilité : Identification rapide par pays et type
• Évolutivité : Support de nouveaux pays facilement

3. Validation des Données

• Contraintes métier : Vérification des règles business
• Intégrité référentielle : Cohérence des relations
• Validation en temps réel : Feedback immédiat
• Gestion d'erreurs : Messages explicites

💡 Exemples d'Utilisation

Créer un Point Focal

{
  "lastName": "Doe",
  "firstName": "John",
  "email": "john.doe@focalpoint.com",
  "phone": "+229123456789",
  "password": "SecurePass123!",
  "countryId": 15,
  "stateId": 106,
  "type": "FOCAL_POINT",
  "localityIds": ["locality-uuid-1", "locality-uuid-2"]
}

Rechercher des Agents par Type

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

Affecter un Agent à Plusieurs Localités

{
  "agentId": "agent-uuid-123",
  "localityIds": ["locality-cotonou", "locality-porto-novo"],
  "isPrimary": false
}

---

🎯 Le module Agents Management offre une gestion complète des agents avec génération automatique de codes, affectation aux localités et hiérarchie entre points focaux et agents pour optimiser la couverture territoriale.