# Réservations CSV & Portail Carrier

---

## Vue d'ensemble

Le système de réservation CSV permet aux admins de créer des réservations en important des fichiers CSV et d'envoyer automatiquement un **lien magique** aux transporteurs pour qu'ils acceptent ou rejettent via un portail dédié.

---

## Workflow complet

```
1. Admin upload CSV → création csv_bookings
2. Admin assigne un carrier à la réservation
3. Système envoie email avec magic link (expiry 1h)
4. Carrier clique → authentification automatique (token URL)
5. Carrier voit les détails → Accept ou Reject
6. Activité logguée dans carrier_activities
7. Admin voit le statut mis à jour en dashboard
```

---

## API — Réservations CSV (Admin)

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | /api/v1/csv-bookings | Liste des réservations CSV |
| POST | /api/v1/csv-bookings | Créer une réservation CSV |
| GET | /api/v1/csv-bookings/:id | Détail d'une réservation |
| PATCH | /api/v1/csv-bookings/:id | Mettre à jour |
| DELETE | /api/v1/csv-bookings/:id | Supprimer |
| POST | /api/v1/csv-bookings/:id/assign-carrier | Assigner un carrier |
| POST | /api/v1/csv-bookings/:id/send-magic-link | Envoyer le lien magique |

---

## API — Portail Carrier

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | /api/v1/carrier/auth | Auth via magic link token |
| GET | /api/v1/carrier/booking | Voir la réservation assignée |
| POST | /api/v1/carrier/booking/accept | Accepter |
| POST | /api/v1/carrier/booking/reject | Rejeter |
| POST | /api/v1/carrier/booking/documents | Uploader des documents |

### Authentification portail carrier

Le lien magique contient un token unique :
```
https://app.xpeditis.com/carrier/auth?token=xxxxxxxx
```

Le token est stocké dans `csv_bookings.carrier_magic_link_token` (hashé).
Expiry : 1 heure. Si expiré, l'admin doit renvoyer un nouveau lien.

---

## Statuts des réservations CSV

| Statut | Description |
|--------|-------------|
| pending | En attente d'assignation carrier |
| sent | Lien magique envoyé au carrier |
| accepted | Carrier a accepté |
| rejected | Carrier a refusé |
| in_transit | En cours de transport |
| delivered | Livré |

---

## Pages frontend

| Route | Description |
|-------|-------------|
| /dashboard/csv-bookings | Liste admin des réservations CSV |
| /carrier/auth | Page d'auth carrier (via magic link) |
| /carrier/booking | Dashboard carrier (accept/reject) |
| /carrier/documents | Upload documents carrier |

---

## Import CSV (upload admin)

Le fichier CSV peut être uploadé via `POST /api/v1/admin/csv-rates/upload`.

Format des colonnes requis : voir [../csv-system/CSV_RATE_SYSTEM.md](../csv-system/CSV_RATE_SYSTEM.md).

---

## Profils carrier

Les carriers qui utilisent le portail ont un `CarrierProfile` lié à leur `Organization`.
Chaque action (accept, reject, document upload) est tracée dans `carrier_activities`.

```sql
SELECT ca.action, ca.created_at, cb.booking_number
FROM carrier_activities ca
JOIN csv_bookings cb ON cb.id = ca.csv_booking_id
WHERE ca.carrier_profile_id = 'xxx'
ORDER BY ca.created_at DESC;
```

---

## Email magic link

Template MJML dans `apps/backend/src/infrastructure/email/templates/`.

Variables disponibles :
- `bookingNumber` — numéro de réservation
- `magicLink` — URL avec token
- `expiresIn` — durée de validité ("1 heure")
- `carrierName` — nom du carrier