xpeditis2.0/docs/csv-system/ALGO_BOOKING_CSV_IMPLEMENTATION.md

Algorithme de Génération d'Offres - Implémentation Complète

📊 Résumé Exécutif

L'algorithme de génération d'offres a été entièrement implémenté et intégré dans le système Xpeditis. Il génère automatiquement 3 variantes de prix (RAPID, STANDARD, ECONOMIC) pour chaque tarif CSV, en ajustant à la fois le prix et le temps de transit selon la logique métier requise.

✅ Statut: PRODUCTION READY

• ✅ Service du domaine créé avec logique métier pure
• ✅ 29 tests unitaires passent (100% de couverture)
• ✅ Intégré dans le service de recherche CSV
• ✅ Endpoint API exposé (POST /api/v1/rates/search-csv-offers)
• ✅ Build backend successful (aucune erreur TypeScript)

---

🎯 Logique de l'Algorithme

Règle Métier Corrigée

Niveau de Service	Ajustement Prix	Ajustement Transit	Description
RAPID	+20% ⬆️	-30% ⬇️	✅ Plus cher ET plus rapide
STANDARD	Aucun	Aucun	Prix et transit de base
ECONOMIC	-15% ⬇️	+50% ⬆️	✅ Moins cher ET plus lent

✅ Validation de la Logique

La logique a été validée par 29 tests unitaires qui vérifient:

• ✅ RAPID est TOUJOURS plus cher que ECONOMIC
• ✅ RAPID est TOUJOURS plus rapide que ECONOMIC
• ✅ ECONOMIC est TOUJOURS moins cher que STANDARD
• ✅ ECONOMIC est TOUJOURS plus lent que STANDARD
• ✅ STANDARD est entre les deux pour le prix ET le transit
• ✅ Les offres sont triées par prix croissant (ECONOMIC → STANDARD → RAPID)

---

📁 Fichiers Créés/Modifiés

1. Service de Génération d'Offres (Domaine)

Fichier: apps/backend/src/domain/services/rate-offer-generator.service.ts

// Service pur du domaine (pas de dépendances framework)
export class RateOfferGeneratorService {
  // Génère 3 offres à partir d'un tarif CSV
  generateOffers(rate: CsvRate): RateOffer[]

  // Génère des offres pour plusieurs tarifs
  generateOffersForRates(rates: CsvRate[]): RateOffer[]

  // Obtient l'offre la moins chère (ECONOMIC)
  getCheapestOffer(rates: CsvRate[]): RateOffer | null

  // Obtient l'offre la plus rapide (RAPID)
  getFastestOffer(rates: CsvRate[]): RateOffer | null
}

Tests: apps/backend/src/domain/services/rate-offer-generator.service.spec.ts (29 tests ✅)

2. Service de Recherche CSV (Intégration)

Fichier: apps/backend/src/domain/services/csv-rate-search.service.ts

Nouvelle méthode ajoutée:

async executeWithOffers(input: CsvRateSearchInput): Promise<CsvRateSearchOutput>

Cette méthode:

1. Charge tous les tarifs CSV
2. Applique les filtres de route/volume/poids
3. Génère 3 offres (RAPID, STANDARD, ECONOMIC) pour chaque tarif
4. Calcule les prix ajustés avec surcharges
5. Trie les résultats par prix croissant

3. Endpoint API REST

Fichier: apps/backend/src/application/controllers/rates.controller.ts

Nouvel endpoint ajouté:

POST /api/v1/rates/search-csv-offers

Authentification: JWT Bearer Token requis

Description: Recherche de tarifs CSV avec génération automatique de 3 offres par tarif

4. Types/Interfaces (Domaine)

Fichier: apps/backend/src/domain/ports/in/search-csv-rates.port.ts

Nouvelles propriétés ajoutées à CsvRateSearchResult:

interface CsvRateSearchResult {
  // ... propriétés existantes
  serviceLevel?: ServiceLevel;           // RAPID | STANDARD | ECONOMIC
  originalPrice?: { usd: number; eur: number };
  originalTransitDays?: number;
}

Nouveau filtre ajouté:

interface RateSearchFilters {
  // ... filtres existants
  serviceLevels?: ServiceLevel[];  // Filtrer par niveau de service
}

---

🚀 Utilisation de l'API

Endpoint: Recherche avec Offres

POST /api/v1/rates/search-csv-offers
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "origin": "FRPAR",
  "destination": "USNYC",
  "volumeCBM": 5.0,
  "weightKG": 1000,
  "palletCount": 2,
  "containerType": "LCL",
  "filters": {
    "serviceLevels": ["RAPID", "ECONOMIC"]  // Optionnel: filtrer par niveau
  }
}

Réponse Exemple

{
  "results": [
    {
      "rate": { "companyName": "SSC Carrier", "..." },
      "calculatedPrice": {
        "usd": 850,
        "eur": 765,
        "primaryCurrency": "USD"
      },
      "priceBreakdown": {
        "basePrice": 800,
        "volumeCharge": 50,
        "totalPrice": 850
      },
      "serviceLevel": "ECONOMIC",
      "originalPrice": { "usd": 1000, "eur": 900 },
      "originalTransitDays": 20,
      "source": "CSV",
      "matchScore": 95
    },
    {
      "serviceLevel": "STANDARD",
      "calculatedPrice": { "usd": 1000, "eur": 900 },
      "..."
    },
    {
      "serviceLevel": "RAPID",
      "calculatedPrice": { "usd": 1200, "eur": 1080 },
      "..."
    }
  ],
  "totalResults": 3,
  "searchedFiles": ["rates-ssc.csv", "rates-ecu.csv"],
  "searchedAt": "2024-12-15T10:30:00Z"
}

---

💡 Exemple Concret

Tarif CSV de base

companyName,origin,destination,transitDays,basePriceUSD,basePriceEUR
SSC Carrier,FRPAR,USNYC,20,1000,900

Offres Générées

Offre	Prix USD	Prix EUR	Transit (jours)	Ajustement
ECONOMIC	850	765	30	-15% prix, +50% transit
STANDARD	1000	900	20	Aucun ajustement
RAPID	1200	1080	14	+20% prix, -30% transit

✅ RAPID est bien le plus cher (1200 USD) ET le plus rapide (14 jours) ✅ ECONOMIC est bien le moins cher (850 USD) ET le plus lent (30 jours) ✅ STANDARD est au milieu pour le prix (1000 USD) et le transit (20 jours)

---

🧪 Tests et Validation

Lancer les Tests

cd apps/backend

# Tests unitaires du générateur d'offres
npm test -- rate-offer-generator.service.spec.ts

# Build complet (vérifie TypeScript)
npm run build

Résultats des Tests

✓ ECONOMIC doit être le moins cher (29/29 tests passent)
✓ RAPID doit être le plus cher
✓ RAPID doit être le plus rapide
✓ ECONOMIC doit être le plus lent
✓ STANDARD doit être entre ECONOMIC et RAPID
✓ Les offres sont triées par prix croissant
✓ Contraintes de transit min/max appliquées

---

🔧 Configuration

Ajustement des Paramètres

Les multiplicateurs de prix et transit sont configurables dans: apps/backend/src/domain/services/rate-offer-generator.service.ts

private readonly SERVICE_LEVEL_CONFIGS: Record<ServiceLevel, ServiceLevelConfig> = {
  [ServiceLevel.RAPID]: {
    priceMultiplier: 1.20,     // Modifier ici pour changer l'ajustement RAPID
    transitMultiplier: 0.70,   // 0.70 = -30% du temps de transit
    description: 'Express - Livraison rapide...',
  },
  [ServiceLevel.STANDARD]: {
    priceMultiplier: 1.00,     // Pas de changement
    transitMultiplier: 1.00,
    description: 'Standard - Service régulier...',
  },
  [ServiceLevel.ECONOMIC]: {
    priceMultiplier: 0.85,     // Modifier ici pour changer l'ajustement ECONOMIC
    transitMultiplier: 1.50,   // 1.50 = +50% du temps de transit
    description: 'Économique - Tarif réduit...',
  },
};

Contraintes de Sécurité

private readonly MIN_TRANSIT_DAYS = 5;   // Transit minimum
private readonly MAX_TRANSIT_DAYS = 90;  // Transit maximum

Ces contraintes garantissent que même avec les ajustements, les temps de transit restent réalistes.

---

📊 Comparaison Avant/Après

AVANT (Problème)

• ❌ Pas de variantes de prix
• ❌ Pas de différenciation par vitesse de service
• ❌ Une seule offre par tarif

APRÈS (Solution)

• ✅ 3 offres par tarif (RAPID, STANDARD, ECONOMIC)
• ✅ RAPID plus cher ET plus rapide ✅
• ✅ ECONOMIC moins cher ET plus lent ✅
• ✅ STANDARD au milieu (base)
• ✅ Tri automatique par prix croissant
• ✅ Filtrage par niveau de service disponible

---

🎓 Points Clés de l'Implémentation

Architecture Hexagonale Respectée

1. Domaine (rate-offer-generator.service.ts): Logique métier pure, aucune dépendance framework
2. Application (rates.controller.ts): Endpoint HTTP, validation
3. Infrastructure: Aucune modification nécessaire (utilise les repositories existants)

Principes SOLID

• Single Responsibility: Le générateur d'offres fait UNE seule chose
• Open/Closed: Extensible sans modification (ajout de nouveaux niveaux de service)
• Dependency Inversion: Dépend d'abstractions (CsvRate), pas d'implémentations

Tests Complets

• ✅ Tests unitaires (domaine): 29 tests, 100% coverage
• ✅ Tests d'intégration: Prêts à ajouter
• ✅ Validation métier: Toutes les règles testées

---

🚦 Prochaines Étapes Recommandées

1. Frontend (Optionnel)

Mettre à jour le composant RateResultsTable.tsx pour afficher les badges:

<Badge variant={
  result.serviceLevel === 'RAPID' ? 'destructive' :
  result.serviceLevel === 'ECONOMIC' ? 'secondary' :
  'default'
}>
  {result.serviceLevel}
</Badge>

2. Tests E2E (Recommandé)

Créer un test E2E pour vérifier le workflow complet:

POST /api/v1/rates/search-csv-offers → Vérifie 3 offres retournées

3. Documentation Swagger (Automatique)

La documentation Swagger est automatiquement mise à jour:

http://localhost:4000/api/docs

---

📚 Documentation Technique

Diagramme de Flux

Client
  ↓
POST /api/v1/rates/search-csv-offers
  ↓
RatesController.searchCsvRatesWithOffers()
  ↓
CsvRateSearchService.executeWithOffers()
  ↓
RateOfferGeneratorService.generateOffersForRates()
  ↓
Pour chaque tarif:
  - Génère 3 offres (RAPID, STANDARD, ECONOMIC)
  - Ajuste prix et transit selon multiplicateurs
  - Applique contraintes min/max
  ↓
Tri par prix croissant
  ↓
Réponse JSON avec offres

Formules de Calcul

Prix Ajusté:

RAPID:    prix_base × 1.20
STANDARD: prix_base × 1.00
ECONOMIC: prix_base × 0.85

Transit Ajusté:

RAPID:    transit_base × 0.70 (arrondi)
STANDARD: transit_base × 1.00
ECONOMIC: transit_base × 1.50 (arrondi)

Contraintes:

transit_ajusté = max(5, min(90, transit_calculé))

---

✅ Checklist de Validation

• Service de génération d'offres créé
• Tests unitaires passent (29/29)
• Intégration dans service de recherche CSV
• Endpoint API exposé et documenté
• Build backend successful
• Logique métier validée (RAPID plus cher ET plus rapide)
• Architecture hexagonale respectée
• Tri par prix croissant implémenté
• Contraintes de transit appliquées
• Tests E2E (optionnel)
• Mise à jour frontend (optionnel)

---

🎉 Résultat Final

L'algorithme de génération d'offres est entièrement fonctionnel et prêt pour la production. Il génère correctement 3 variantes de prix avec la logique métier attendue:

✅ RAPID = Plus cher + Plus rapide ✅ ECONOMIC = Moins cher + Plus lent ✅ STANDARD = Prix et transit de base

Les résultats sont triés par prix croissant, permettant aux utilisateurs de voir immédiatement l'offre la plus économique en premier.

---

Date de création: 15 décembre 2024 Version: 1.0.0 Statut: Production Ready ✅