🚀 Trade Service - Vue d'ensemble

Le Trade Service est un microservice central qui gère toutes les opérations commerciales dans l'écosystème FreeTrade. Il offre une suite complète de fonctionnalités pour les transporteurs, clients et agents.

🎯 Objectif principal

Centraliser la gestion des opérations commerciales dans un écosystème de transport et logistique moderne, en permettant aux utilisateurs de :

Gérer leurs plaintes et réclamations
Participer à des discussions communautaires
Consulter des annonces officielles importantes
Accéder à des ressources éducatives
Créer et suivre leurs transports

🏗️ Architecture technique

Technologies utilisées

Composant	Technologie	Version	Rôle
Framework	NestJS	11.x	Structure et organisation du code
Base de données	MySQL	8.0+	Stockage des données
ORM	Prisma	6.9+	Accès et gestion de la base de données
Cache	Redis	7.0+	Amélioration des performances
Messagerie	NATS	2.29+	Communication inter-services
Validation	class-validator	-	Contrôle des données d'entrée
Upload	Multer	-	Gestion des fichiers

Communication

Le service utilise NATS comme système de messagerie pour communiquer avec les autres services. Chaque action suit un pattern standardisé : {module}.{action}

Exemples de patterns :

complaint.create - Créer une plainte
transport.findOne - Récupérer un transport
forum.topic.create - Créer un sujet de forum

📦 Modules fonctionnels

Le Trade Service est organisé en 5 modules indépendants :

📋 Complaints - Gestion des plaintes

Objectif : Permettre aux clients de déposer et suivre leurs réclamations
Fonctionnalités : Création, suivi, pièces jointes, historique complet
Statuts : 8 statuts différents (PENDING → RESOLVED)
Workflow : Client → Système → Agent → Résolution

🚛 Transports - Opérations de transport

Objectif : Gérer les opérations de transport et clients
Fonctionnalités : Création, gestion clients, documents, suivi
Types : Camions, camionnettes, motos
Documents : Permis, carte grise, assurance

💬 Forum - Communauté d'entraide

Objectif : Créer une communauté d'entraide entre utilisateurs
Fonctionnalités : Topics, messages, votes, modération
Structure : Catégories → Sujets → Messages → Réponses
Modération : Signalement et gestion des contenus

📢 Announcements - Annonces officielles

Objectif : Diffuser des informations officielles importantes
Fonctionnalités : Annonces, images, ciblage, cache optimisé
Types : Réglementation, maintenance, événements, mises à jour
Priorités : HIGH, MEDIUM, LOW

📚 Tutorials - Ressources éducatives

Objectif : Fournir des ressources éducatives aux utilisateurs
Fonctionnalités : Vidéos, recherche, progression, certification
Niveaux : Débutant, Intermédiaire, Avancé
Durées : Court (5-20min), Moyen (20-60min), Long (60min+)

🔄 Format de réponse standardisé

Toutes les réponses de l'API suivent le même format pour assurer la cohérence :

{
  "success": boolean,    // true = succès, false = erreur
  "message": string,     // Message descriptif
  "result": object,      // Données (null si erreur)
  "errors": object,      // Détails des erreurs
  "except": object       // Informations techniques (dev uniquement)
}

Exemple de succès

{
  "success": true,
  "message": "Transport créé avec succès",
  "result": {
    "id": 123,
    "publicId": "transport-abc-123",
    "loadingNumber": "TRP-2025-001234",
    "status": "PENDING",
    "createdAt": "2025-07-21T10:30:00Z"
  },
  "errors": null,
  "except": null
}

Exemple d'erreur

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

📊 Pagination standardisée

Les listes d'éléments sont paginées avec des métadonnées complètes :

{
  "success": true,
  "message": "Liste des éléments",
  "result": {
    "meta": {
      "total": 156,           // Total d'éléments
      "total_pages": 16,      // Nombre de pages
      "current_page": 2,      // Page actuelle
      "limit": 10,            // Éléments par page
      "next_page": 3,         // Page suivante
      "previous_page": 1,     // Page précédente
      "first_page": 1,        // Première page
      "last_page": 16         // Dernière page
    },
    "data": [
      // ... éléments de la page
    ]
  }
}

🔒 Sécurité et validation

Validation des données

class-validator : Validation automatique des DTOs
Propriétés non déclarées : Suppression automatique
Types de fichiers : Contrôle lors des uploads
Taille des fichiers : Limitation à 10MB maximum

Gestion des erreurs

Erreurs techniques : Exposées uniquement en développement
Messages utilisateur : Standardisés et localisés
Logging : Toutes les exceptions sont loggées

Limitations

Fichiers : 10MB maximum, types JPEG/PNG/PDF
Upload : Maximum 10 fichiers simultanés
Pagination : Maximum 100 éléments par page
Rate limiting : Configurable par endpoint

🚀 Performance et optimisation

Cache Redis

Types de plaintes : 1 heure de TTL
Catégories forum : 1 heure de TTL
Listes paginées : 10 minutes de TTL
Invalidation automatique lors des mises à jour

Base de données

Index sur les champs fréquemment recherchés
Pagination pour éviter les gros volumes
Sélection des champs nécessaires uniquement
Requêtes parallèles quand possible

📈 Statistiques du service

163 endpoints documentés
5 modules fonctionnels
8 statuts de plaintes différents
3 niveaux de difficulté pour les tutoriels
Architecture microservice moderne
Communication asynchrone via NATS

Module	Description	Endpoints principaux
Complaints	Gestion des plaintes	`create`, `findAll`, `update`, `statusHistory`
Transports	Opérations de transport	`create`, `findAll`, `vehicleTypes`
Forum	Communauté d'entraide	`topic.create`, `message.create`, `message.like`
Announcements	Annonces officielles	`findAll`, `findOne`, `categories`
Tutorials	Ressources éducatives	`findAll`, `complete`, `progress`

Prochaine étape : Explorez les modules individuels pour découvrir tous les endpoints disponibles et leurs spécifications détaillées.

🎯 Objectif principal​

🏗️ Architecture technique​

Technologies utilisées​

Communication​

📦 Modules fonctionnels​

📋 Complaints - Gestion des plaintes​

🚛 Transports - Opérations de transport​

💬 Forum - Communauté d'entraide​

📢 Announcements - Annonces officielles​

📚 Tutorials - Ressources éducatives​

🔄 Format de réponse standardisé​

Exemple de succès​

Exemple d'erreur​

📊 Pagination standardisée​

🔒 Sécurité et validation​

Validation des données​

Gestion des erreurs​

Limitations​

🚀 Performance et optimisation​

Cache Redis​

Base de données​

📈 Statistiques du service​

🔗 Navigation rapide​