Skip to main content

🎯 Premiers pas avec FreeTrade

Maintenant que FreeTrade est installé et fonctionne, découvrons ensemble les fonctionnalités principales à travers des exemples pratiques.

🔐 Authentification - Votre première connexion​

Obtenir un token d'accès​

# Connexion avec les identifiants par défaut
curl -X POST http://localhost:3004/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin@example.com",
    "password": "password123"
  }'

Réponse attendue :

{
  "success": true,
  "message": "Connexion réussie",
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin@example.com",
      "firstName": "Admin",
      "lastName": "User"
    }
  }
}

Sauvegarder le token​

# Extraire et sauvegarder le token
TOKEN=$(curl -s -X POST http://localhost:3004/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin@example.com",
    "password": "password123"
  }' | jq -r '.result.access_token')

echo "Token sauvegardé: $TOKEN"

👤 Exploration du profil utilisateur​

Récupérer votre profil​

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3004/auth/profile

Ce que vous découvrirez :

  • Informations personnelles complètes
  • Rôles et permissions
  • Statut du compte
  • Informations de session

👥 Gestion des utilisateurs (Admin)​

Lister les utilisateurs existants​

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/users?page=1&limit=5"

Créer votre premier utilisateur​

curl -X POST http://localhost:3004/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "password": "securePassword123",
    "confirmPassword": "securePassword123",
    "roleId": 2,
    "status": "ACTIVE"
  }'

Points clés :

  • Le mot de passe doit faire au moins 6 caractères
  • L'email doit être unique
  • Le roleId détermine les permissions

🚛 Votre premier transport​

Créer un transport​

curl -X POST http://localhost:3004/trade/transports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chargerFirstName": "Marie",
    "chargerLastName": "Kouam",
    "chargerPhone": "+237123456789",
    "vehicleTypeId": 1,
    "loadingPoint": "Marché Central, Douala",
    "unloadingPoint": "Gare Routière, Yaoundé",
    "vehiclePlateNumber": "CM-456-DEF",
    "productLabel": "Fruits et légumes",
    "productQuantity": 500,
    "averageWeight": 1.2,
    "averageUnitPrice": 200,
    "totalProductValue": 100000
  }'

Consulter vos transports​

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/trade/transports?page=1&limit=10"

📋 Système de plaintes​

Créer une plainte​

curl -X POST http://localhost:3004/trade/complaints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transportId": 1,
    "customerId": 1,
    "complaintTypeId": 1,
    "label": "Retard de transport",
    "description": "Le transport prévu à 8h a eu 2 heures de retard sans notification préalable.",
    "location": "Gare Routière de Yaoundé",
    "amountPaid": 2500,
    "timeLost": 120,
    "status": "PENDING"
  }'

Suivre vos plaintes​

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/trade/complaints?status=PENDING"

💬 Forum communautaire​

Créer votre premier topic​

curl -X POST http://localhost:3004/trade/forum/topics \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Conseils pour optimiser les coûts de transport",
    "description": "Partageons nos expériences pour réduire les coûts",
    "content": "Bonjour à tous ! J'aimerais connaître vos astuces pour optimiser les coûts de transport de marchandises entre Douala et Yaoundé.",
    "categoryId": 1,
    "userId": 1
  }'

Participer aux discussions​

# Lister les topics populaires
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/trade/forum/topics?sortBy=popularity&limit=5"

# Ajouter un message à un topic
curl -X POST http://localhost:3004/trade/forum/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": 1,
    "content": "Excellente question ! Personnellement, je recommande de grouper les livraisons pour optimiser les trajets.",
    "userId": 1
  }'

📊 Découvrir les statistiques​

Statistiques des plaintes​

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3004/admin/complaints/stats

Statistiques des transports​

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3004/admin/transports/stats

Statistiques des acteurs​

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3004/admin/actors/stats

🔍 Techniques de recherche avancée​

Recherche avec filtres​

# Rechercher des utilisateurs par nom
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/users?search=john&status=ACTIVE"

# Filtrer les transports par localisation
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/transports?loadingPoint=Douala&unloadingPoint=Yaoundé"

# Plaintes par période
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/complaints?startDate=2024-01-01&endDate=2024-12-31&status=RESOLVED"

Pagination efficace​

# Première page (10 éléments)
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/users?page=1&limit=10"

# Page suivante
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/users?page=2&limit=10"

🛠️ Gestion des erreurs courantes​

Erreur 401 - Token expiré​

# Si vous obtenez une erreur 401, reconnectez-vous
if curl -s -H "Authorization: Bearer $TOKEN" http://localhost:3004/auth/profile | grep -q "INVALID_TOKEN"; then
  echo "Token expiré, reconnexion..."
  TOKEN=$(curl -s -X POST http://localhost:3004/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username": "admin@example.com", "password": "password123"}' \
    | jq -r '.result.access_token')
fi

Erreur 400 - Données invalides​

{
  "success": false,
  "message": "Données de validation invalides",
  "errors": [
    "email must be an email",
    "password must be longer than or equal to 6 characters"
  ]
}

Solution : Vérifiez que toutes les données respectent les contraintes de validation.

🎯 Bonnes pratiques​

1. Sécurité du token​

  • Ne jamais exposer le token dans les logs
  • Renouveler régulièrement le token
  • Utiliser HTTPS en production

2. Gestion des erreurs​

  • Toujours vérifier le champ success dans les réponses
  • Implémenter une logique de retry pour les erreurs temporaires
  • Logger les erreurs pour le débogage

3. Performance​

  • Utiliser la pagination pour les grandes listes
  • Implémenter un cache côté client pour les données statiques
  • Limiter les requêtes simultanées

🎉 Félicitations !​

Vous maîtrisez maintenant les bases de FreeTrade ! Vous savez :

  • ✅ Vous authentifier et gérer votre profil
  • ✅ Créer et gérer des utilisateurs
  • ✅ Enregistrer des transports
  • ✅ Gérer des plaintes
  • ✅ Participer au forum
  • ✅ Consulter les statistiques
  • ✅ Utiliser les filtres et la recherche

🚀 Prochaines étapes​

  1. Architecture détaillée - Comprendre le système en profondeur
  2. API Reference complète - Explorer tous les endpoints
  3. Déploiement en production - Mettre en production
  4. Résolution de problèmes - Gérer les incidents

Besoin d'aide ? La documentation complète est disponible dans les sections suivantes !