xpeditis2.0/docs/features/bookings.md

Réservations standard

---

Workflow de réservation (4 étapes max)

1. Sélection de l'offre (vérification dispo temps réel)
2. Informations expéditeur / destinataire
3. Détails conteneur
4. Confirmation + CGU → Génération booking number

---

Numéro de réservation

Format : WCM-YYYY-XXXXXX (XXXXXX = 6 caractères alphanumériques uniques)

Exemple : WCM-2026-A3F7K2

---

Statuts

Statut	Description
draft	Brouillon (en cours de création)
confirmed	Confirmé
shipped	En transit
delivered	Livré
cancelled	Annulé

---

API

Méthode	Route	Description
GET	/api/v1/bookings	Liste (paginée, filtrable)
POST	/api/v1/bookings	Créer une réservation
GET	/api/v1/bookings/:id	Détail
PATCH	/api/v1/bookings/:id	Mettre à jour
DELETE	/api/v1/bookings/:id	Annuler
GET	/api/v1/bookings/:id/pdf	Générer PDF
POST	/api/v1/bookings/export	Export Excel/PDF

Exemple création

POST /api/v1/bookings
Authorization: Bearer <token>

{
  "rateQuoteId": "uuid-de-la-cotation",
  "shipper": {
    "name": "Acme Corp",
    "address": "123 Main St",
    "country": "FR"
  },
  "consignee": {
    "name": "Shanghai Trading",
    "address": "456 Nanjing Rd",
    "country": "CN"
  },
  "containers": [
    {
      "type": "40HC",
      "cargoDescription": "Electronic components",
      "isHazmat": false
    }
  ],
  "notes": "Fragile cargo"
}

---

Post-booking automatique

Après création d'une réservation :

1. Audit log — action BOOKING_CREATED
2. Notification WebSocket — push en temps réel
3. Webhooks — événement BOOKING_CREATED envoyé aux abonnés
4. Email confirmation — template MJML
5. PDF — généré via pdfkit, stocké sur MinIO

---

Filtres disponibles

GET /api/v1/bookings?status=confirmed&carrierId=xxx&page=1&limit=20
  &startDate=2026-01-01&endDate=2026-12-31
  &search=WCM-2026  (recherche floue sur numéro, expéditeur, destinataire)

---

Dashboard

Le dashboard agrège :

• KPI cards : bookings/mois, TEUs, montant total
• Graphiques 6 mois (recharts)
• Alertes (retards, confirmations en attente)
• Table interactive avec TanStack Table (tri, filtres, pagination, virtual scroll)

Endpoint : GET /api/v1/dashboard/stats