# Tests Curl - Module Attelages (Couplings)

## Configuration

```bash
TOKEN="votre_token_bearer_ici"
BASE_URL="https://apiparcapp.jrbxsolutions.com"
# Ou en local : BASE_URL="http://apiparcapp.test"
```

## 1. GET `/api/couplings` - Liste des attelages actifs

```bash
curl -X GET "${BASE_URL}/api/couplings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

**Réponse attendue** : Array de `CouplingWithDetails[]` (actifs uniquement)

---

## 2. GET `/api/couplings/history` - Historique complet

```bash
curl -X GET "${BASE_URL}/api/couplings/history" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

**Réponse attendue** : Array de `CouplingWithDetails[]` (actifs + terminés)

---

## 3. GET `/api/couplings/vehicle/{vehicleId}` - Attelage actif d'un véhicule

```bash
# Remplacez 5 par l'ID d'un véhicule existant
curl -X GET "${BASE_URL}/api/couplings/vehicle/5" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

**Réponse attendue** :
- `200 OK` : Objet `CouplingWithDetails` si attelage actif trouvé
- `404 Not Found` : Si aucun attelage actif pour ce véhicule

**Note** : Route corrigée de `/couplings/{vehicleId}` vers `/couplings/vehicle/{vehicleId}` pour éviter collision avec `PATCH /couplings/{coupling}`.

---

## 4. POST `/api/couplings` - Créer un attelage

```bash
curl -X POST "${BASE_URL}/api/couplings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": 5,
    "trailerId": 3,
    "chauffeurId": 2,
    "apprentiIds": [4, 7],
    "startAt": "2025-12-30T10:30:00.000Z"
  }'
```

**Réponse attendue** : `201 Created` avec objet `VehicleTrailerCoupling` (sans relations)

**Erreurs possibles** :
- `422 Validation Error` : Si contraintes métier violées (véhicule/remorque/chauffeur/apprenti déjà attelé)
- `409 Conflict` : Si race condition détectée (rare, mais possible sans verrous)

**Note** : Les contraintes sont vérifiées de manière atomique avec transactions et verrous pour éviter les race conditions.

---

## 5. PATCH `/api/couplings/{id}` - Détacher un attelage

```bash
# Remplacez 1 par l'ID de l'attelage à détacher
curl -X PATCH "${BASE_URL}/api/couplings/1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "endAt": "2025-12-30T18:00:00.000Z"
  }'
```

**Réponse attendue** : `200 OK` avec objet `VehicleTrailerCoupling` mis à jour (`active = false`, `endAt` défini)

**Alternative (sans date de fin)** :
```bash
curl -X PATCH "${BASE_URL}/api/couplings/1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Dans ce cas, `endAt` sera automatiquement défini à `now()`.

---

## Tests de Contraintes Métier

### Test 1 : Tentative de créer un deuxième attelage pour le même véhicule

```bash
# Créer un premier attelage
curl -X POST "${BASE_URL}/api/couplings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": 5,
    "chauffeurId": 2,
    "apprentiIds": [4],
    "startAt": "2025-12-30T10:30:00.000Z"
  }'

# Tentative de créer un deuxième attelage pour le même véhicule (doit échouer)
curl -X POST "${BASE_URL}/api/couplings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": 5,
    "chauffeurId": 3,
    "apprentiIds": [7],
    "startAt": "2025-12-30T11:00:00.000Z"
  }'
```

**Résultat attendu** : `422 Validation Error` avec message "Ce véhicule a déjà un attelage actif."

---

### Test 2 : Test de race condition (double clic simulé)

**Note** : Ce test nécessite deux requêtes simultanées. En production, les verrous `lockForUpdate()` empêchent ce problème.

```bash
# Lancer deux requêtes POST simultanées (dans deux terminaux)
# Terminal 1 :
curl -X POST "${BASE_URL}/api/couplings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"vehicleId": 5, "chauffeurId": 2, "apprentiIds": [4], "startAt": "2025-12-30T10:30:00.000Z"}'

# Terminal 2 (lancer immédiatement après) :
curl -X POST "${BASE_URL}/api/couplings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"vehicleId": 5, "chauffeurId": 3, "apprentiIds": [7], "startAt": "2025-12-30T10:30:00.000Z"}'
```

**Résultat attendu** : Une seule requête réussit (`201 Created`), l'autre échoue (`422 Validation Error`). Les verrous garantissent l'atomicité.

---

## Vérification des Réponses

### Format camelCase

Toutes les réponses doivent utiliser camelCase :
- ✅ `vehicleId`, `trailerId`, `chauffeurId`, `startAt`, `endAt`, `createdAt`, `updatedAt`
- ❌ `vehicle_id`, `trailer_id`, `chauffeur_id`, `start_at`, `end_at`, `created_at`, `updated_at`

### Dates ISO 8601

Toutes les dates doivent être en ISO 8601 :
- ✅ `"2025-12-30T10:30:00.000000Z"`
- ❌ `"2025-12-30 10:30:00"` ou timestamps Unix

### URLs absolues

Toutes les `photoUrl` doivent être absolues :
- ✅ `"https://apiparcapp.jrbxsolutions.com/storage/vehicles/photo.jpg"`
- ❌ `"/storage/vehicles/photo.jpg"` ou `"storage/vehicles/photo.jpg"`

---

**Document généré le** : 2025-12-30  
**Statut** : Prêt pour tests après implémentation