# Recherche de tarifs

---

## Deux types de recherche

| Type | Description | Endpoint |
|------|-------------|----------|
| FCL (Full Container Load) | Tarifs via connecteurs carriers (Maersk, MSC, etc.) | POST /api/v1/rates/search |
| CSV / LCL | Tarifs chargés depuis des fichiers CSV | POST /api/v1/rates/csv-search |

---

## Recherche FCL — Carriers API

### Endpoint

```
POST /api/v1/rates/search
Authorization: Bearer <token>

{
  "origin": "NLRTM",
  "destination": "CNSHA",
  "containerType": "40HC",
  "mode": "FCL",
  "departureDate": "2026-06-01",
  "hazmat": false
}
```

### Réponse

```json
{
  "results": [
    {
      "id": "uuid",
      "carrier": { "name": "Maersk", "code": "MAERSK", "logoUrl": "..." },
      "origin": { "code": "NLRTM", "name": "Rotterdam" },
      "destination": { "code": "CNSHA", "name": "Shanghai" },
      "baseFreight": 1850.00,
      "surcharges": [
        { "type": "BAF", "amount": 250.00, "currency": "USD" }
      ],
      "totalAmount": 2100.00,
      "currency": "USD",
      "transitDays": 28,
      "etd": "2026-06-01T00:00:00Z",
      "eta": "2026-06-29T00:00:00Z",
      "availability": 50,
      "validUntil": "2026-05-13T10:15:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "pageSize": 20
}
```

### Cache Redis

- Clé : `rate:{origin}:{destination}:{containerType}`
- TTL : 15 minutes
- Les cotations expirent automatiquement après 15min (`valid_until`)

### Carriers intégrés

| Carrier | Code | SCAC |
|---------|------|------|
| Maersk | MAERSK | MAEU |
| MSC | MSC | MSCU |
| CMA CGM | CMACGM | CMDU |
| Hapag-Lloyd | HAPAG | HLCU |
| ONE | ONE | ONEY |

Chaque carrier a son connecteur dans `apps/backend/src/infrastructure/carriers/`.
Circuit breaker via `opossum` : timeout 5s, bascule sur fallback si indisponible.

---

## Recherche CSV

### Endpoint

```
POST /api/v1/rates/csv-search
Authorization: Bearer <token>

{
  "origin": "NLRTM",
  "destination": "USNYC",
  "volumeCBM": 25.5,
  "weightKG": 3500,
  "palletCount": 10,
  "filters": {
    "companies": ["SSC Consolidation"],
    "minPrice": 1000,
    "maxPrice": 3000,
    "currency": "USD"
  }
}
```

### Carriers CSV disponibles

| Company | Type | API |
|---------|------|-----|
| SSC Consolidation | CSV_ONLY | Non |
| ECU Worldwide | CSV_AND_API | Oui |
| TCC Logistics | CSV_ONLY | Non |
| NVO Consolidation | CSV_ONLY | Non |

Les fichiers CSV sont dans `apps/backend/src/infrastructure/storage/csv-storage/rates/`.

### Calcul de prix CSV

```typescript
// Freight class : prendre le max de volume-based ou weight-based
const volumePrice = volumeCBM * pricePerCBM;
const weightPrice = weightKG * pricePerKG;
const freightPrice = Math.max(volumePrice, weightPrice);
const totalPrice = freightPrice + surchargeBAF + surchargeCAF;
```

---

## Recherche de ports

Autocomplete avec recherche floue (pg_trgm) :

```
GET /api/v1/ports/search?q=rotterdam&limit=10
```

~10 000 ports UN/LOCODE seedés en base.

---

## Export des résultats

Les résultats peuvent être exportés en PDF ou Excel depuis le frontend.
Voir `apps/frontend/src/utils/` pour les utilitaires d'export.