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`

```typescript
// 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:
```typescript
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é:
```typescript
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`:
```typescript
interface CsvRateSearchResult {
  // ... propriétés existantes
  serviceLevel?: ServiceLevel;           // RAPID | STANDARD | ECONOMIC
  originalPrice?: { usd: number; eur: number };
  originalTransitDays?: number;
}
```

Nouveau filtre ajouté:
```typescript
interface RateSearchFilters {
  // ... filtres existants
  serviceLevels?: ServiceLevel[];  // Filtrer par niveau de service
}
```

---

## 🚀 Utilisation de l'API

### Endpoint: Recherche avec Offres

```http
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

```json
{
  "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

```csv
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

```bash
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`

```typescript
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é

```typescript
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:

```tsx
<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:
```bash
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

- [x] Service de génération d'offres créé
- [x] Tests unitaires passent (29/29)
- [x] Intégration dans service de recherche CSV
- [x] Endpoint API exposé et documenté
- [x] Build backend successful
- [x] Logique métier validée (RAPID plus cher ET plus rapide)
- [x] Architecture hexagonale respectée
- [x] Tri par prix croissant implémenté
- [x] 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 ✅