📋 Trade Complaints - Gestion des plaintes

Le module Complaints permet aux clients de déposer et suivre leurs réclamations liées aux transports.

🎯 Objectif

Permettre aux clients de signaler des problèmes liés à leurs transports avec un système de suivi complet et une traçabilité des actions.

✨ Fonctionnalités principales

• Création de plaintes : Les clients peuvent signaler des problèmes liés à leurs transports
• Suivi en temps réel : Chaque plainte a un statut qui évolue (En attente → En cours → Résolue)
• Pièces jointes : Support pour photos, documents PDF (max 10MB)
• Historique complet : Traçabilité de tous les changements de statut
• Types de plaintes : Retard, marchandise endommagée, service client, etc.

🔄 Workflow typique

1. Client : Crée une plainte en renseignant le numéro de transport
2. Système : Vérifie l'unicité (un transport = une plainte maximum)
3. Agent : Prend en charge et change le statut vers "En cours"
4. Agent : Traite la plainte et la marque comme "Résolue"
5. Client : Reçoit une notification de résolution

📊 Statuts disponibles

Statut	Description	Action suivante
PENDING	En attente de traitement	Agent prend en charge
IN_PROGRESS	En cours de traitement	Agent traite la plainte
UNDER_REVIEW	Sous révision	Validation par superviseur
RESOLVED	Résolue	Notification au client
REJECTED	Rejetée	Explication au client
CLOSED	Fermée	Archivage
REOPENED	Rouverte	Nouveau traitement
ESCALATED	Escaladée	Traitement prioritaire

🔌 Endpoints disponibles

Créer une plainte

POST /trade/complaints

Paramètres :

{
  "transportId": 123,
  "customerId": 456,
  "complaintTypeId": 1,
  "label": "Retard de livraison",
  "description": "Le transport a eu 3 heures de retard sans notification",
  "location": "Yaoundé",
  "amountPaid": 50000,
  "timeLost": 180
}

Réponse de succès :

{
  "success": true,
  "message": "Plainte créée avec succès",
  "result": {
    "id": 123,
    "publicId": "complaint-abc-123",
    "label": "Retard de livraison",
    "status": "PENDING",
    "transportId": 456,
    "createdAt": "2025-07-21T10:30:00Z"
  }
}

Lister les plaintes

GET /trade/complaints?page=1&limit=10&status=PENDING

Paramètres de requête :

• page : Numéro de page (défaut: 1)
• limit : Éléments par page (défaut: 10, max: 100)
• status : Filtrer par statut
• countryId : Filtrer par pays
• complaintTypeId : Filtrer par type de plainte
• startAtFrom : Date de début (format ISO)
• startAtTo : Date de fin (format ISO)
• label : Recherche textuelle dans le titre

Réponse :

{
  "success": true,
  "message": "Liste des plaintes",
  "result": {
    "meta": {
      "total": 156,
      "total_pages": 16,
      "current_page": 2,
      "limit": 10,
      "next_page": 3,
      "previous_page": 1
    },
    "data": [
      {
        "id": 11,
        "publicId": "complaint-def-456",
        "label": "Problème de livraison",
        "status": "PENDING",
        "transport": {
          "id": 789,
          "loadingPoint": "Douala",
          "unloadingPoint": "Yaoundé"
        },
        "createdAt": "2025-07-21T09:15:00Z"
      }
    ]
  }
}

Détail d'une plainte

GET /trade/complaints/{id}

Réponse :

{
  "success": true,
  "message": "Détail de la plainte",
  "result": {
    "id": 123,
    "publicId": "complaint-abc-123",
    "label": "Retard de livraison",
    "description": "Le transport a eu 3 heures de retard...",
    "status": "IN_PROGRESS",
    "location": "Yaoundé",
    "amountPaid": 50000,
    "timeLost": 180,
    "transport": {
      "id": 456,
      "loadingPoint": "Douala",
      "unloadingPoint": "Yaoundé",
      "vehiclePlateNumber": "CM-123-AB"
    },
    "customer": {
      "id": 789,
      "firstName": "Jean",
      "lastName": "Dupont",
      "email": "jean.dupont@example.com"
    },
    "complaintType": {
      "id": 1,
      "name": "Retard",
      "description": "Problème de délai de livraison"
    },
    "attachments": [
      {
        "id": 1,
        "type": "image/jpeg",
        "url": "/uploads/complaint-123/photo1.jpg",
        "filename": "photo_retard.jpg"
      }
    ],
    "createdAt": "2025-07-21T10:30:00Z",
    "updatedAt": "2025-07-21T11:15:00Z"
  }
}

Historique des statuts

GET /trade/complaints/{id}/status-history

Réponse :

{
  "success": true,
  "message": "Historique des statuts",
  "result": [
    {
      "id": 1,
      "status": "PENDING",
      "comment": "Plainte créée par le client",
      "createdBy": {
        "id": 789,
        "name": "Jean Dupont",
        "type": "CUSTOMER"
      },
      "createdAt": "2025-07-21T10:30:00Z"
    },
    {
      "id": 2,
      "status": "IN_PROGRESS",
      "comment": "Prise en charge par l'agent",
      "createdBy": {
        "id": 456,
        "name": "Marie Agent",
        "type": "AGENT"
      },
      "createdAt": "2025-07-21T11:15:00Z"
    }
  ]
}

Types de plaintes

GET /trade/complaints/types

Réponse :

{
  "success": true,
  "message": "Types de plaintes disponibles",
  "result": [
    {
      "id": 1,
      "name": "Retard",
      "description": "Problème de délai de livraison",
      "isActive": true
    },
    {
      "id": 2,
      "name": "Marchandise endommagée",
      "description": "Dégâts sur la marchandise transportée",
      "isActive": true
    },
    {
      "id": 3,
      "name": "Service client",
      "description": "Problème de communication ou service",
      "isActive": true
    }
  ]
}

Upload de fichiers

POST /trade/complaints/upload

Paramètres :

• files : Fichiers à uploader (multipart/form-data)
• complaintId : ID de la plainte (optionnel si création)

Contraintes :

• Taille maximale : 10MB par fichier
• Types autorisés : JPEG, PNG, PDF
• Maximum 10 fichiers par upload

Réponse :

{
  "success": true,
  "message": "Fichiers uploadés avec succès",
  "result": {
    "uploaded": [
      {
        "filename": "photo_retard.jpg",
        "type": "image/jpeg",
        "size": 2048576,
        "url": "/uploads/complaint-123/photo_retard.jpg"
      }
    ],
    "errors": []
  }
}

🔒 Règles de validation

Création de plainte

• transportId : Obligatoire, doit exister
• label : Minimum 3 caractères
• Un transport ne peut avoir qu'une seule plainte
• Email ou téléphone obligatoire pour le client

Upload de fichiers

• Taille : Maximum 10MB par fichier
• Types : JPEG, PNG, PDF uniquement
• Nombre : Maximum 10 fichiers par upload

❌ Gestion des erreurs

Erreur de validation

{
  "success": false,
  "message": "Données invalides",
  "errors": {
    "transportId": "Le numéro de transport est obligatoire",
    "label": "Le titre doit contenir au moins 3 caractères"
  }
}

Plainte déjà existante

{
  "success": false,
  "message": "Une plainte existe déjà pour ce transport",
  "errors": {
    "code": "COMPLAINT_EXISTS",
    "transportId": 123,
    "existingComplaintId": 456
  }
}

Transport non trouvé

{
  "success": false,
  "message": "Transport non trouvé",
  "errors": {
    "code": "TRANSPORT_NOT_FOUND",
    "transportId": 999
  }
}

---

Prochaine section : Transports Trade