# 📖 Guide d'utilisation des services et API

## 🏗️ Architecture générale

```
Contrôleur API
      ↓
  Service (logique métier)
      ↓
  BaseService (CRUD générique)
      ↓
  Modèle Eloquent (BD)
```

## 💻 Utilisation des Services

### Exemple 1 : Injection de dépendance dans un contrôleur

```php
<?php

namespace Modules\MonModule\Http\Controllers;

use Modules\Referentiel\Services\LangueService;

class MyController extends Controller
{
    private $langueService;

    public function __construct(LangueService $langueService)
    {
        $this->langueService = $langueService;
    }

    public function example()
    {
        // Récupérer toutes les langues avec pagination
        $langues = $this->langueService->getAll(10, 1);
        
        // Récupérer une langue par ID
        $langue = $this->langueService->getById(1);
        
        // Créer une nouvelle langue
        $nouvelle = $this->langueService->create([
            'nom' => 'Anglais',
            'tag' => 'EN'
        ]);
        
        // Mettre à jour
        $this->langueService->update(1, [
            'nom' => 'Français',
            'tag' => 'FR'
        ]);
        
        // Supprimer
        $this->langueService->delete(1);
        
        // Vérifier l'existence
        if ($this->langueService->exists(1)) {
            echo "Langue existe";
        }
        
        // Compter les enregistrements
        $total = $this->langueService->count();
    }
}
```

### Exemple 2 : Utilisation dans une command/job

```php
<?php

namespace Modules\MonModule\Console\Commands;

use Modules\Referentiel\Services\PaysService;

class ImportCountries extends Command
{
    public function handle(PaysService $paysService)
    {
        // Créer plusieurs pays
        $countries = [
            ['nom' => 'France', 'tag' => 'FR'],
            ['nom' => 'Belgique', 'tag' => 'BE'],
            ['nom' => 'Suisse', 'tag' => 'CH'],
        ];

        foreach ($countries as $country) {
            $paysService->create($country);
        }

        $this->info('Pays importés avec succès!');
    }
}
```

## 🌐 Utilisation de l'API REST

### Installation du fichier Postman

Vous pouvez importer la collection Postman fournie pour tester facilement l'API.

### Exemples cURL

#### 1. Créer une langue
```bash
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nom": "Français",
    "tag": "FR"
  }'
```

**Réponse (201 Created):**
```json
{
  "success": true,
  "message": "Language created successfully",
  "data": {
    "id": 1,
    "nom": "Français",
    "tag": "FR",
    "created_at": "2026-06-06T19:02:14.000000Z",
    "updated_at": "2026-06-06T19:02:14.000000Z"
  }
}
```

#### 2. Récupérer toutes les langues
```bash
curl -X GET "http://localhost:8000/api/referentiel/languages?page=1&per_page=15" \
  -H "Accept: application/json"
```

**Réponse (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "nom": "Français",
      "tag": "FR",
      "created_at": "2026-06-06T19:02:14.000000Z",
      "updated_at": "2026-06-06T19:02:14.000000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 1
  }
}
```

#### 3. Récupérer une langue
```bash
curl -X GET http://localhost:8000/api/referentiel/languages/1 \
  -H "Accept: application/json"
```

#### 4. Mettre à jour une langue
```bash
curl -X PUT http://localhost:8000/api/referentiel/languages/1 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nom": "Français (France)",
    "tag": "FR_FR"
  }'
```

#### 5. Supprimer une langue
```bash
curl -X DELETE http://localhost:8000/api/referentiel/languages/1 \
  -H "Accept: application/json"
```

#### 6. Gestion des erreurs - Validation
```bash
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -d '{
    "nom": ""
  }'
```

**Réponse (422 Unprocessable Entity):**
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "nom": ["The nom field is required."],
    "tag": ["The tag field is required."]
  }
}
```

#### 7. Ressource non trouvée
```bash
curl -X GET http://localhost:8000/api/referentiel/languages/999 \
  -H "Accept: application/json"
```

**Réponse (404 Not Found):**
```json
{
  "success": false,
  "message": "Language not found"
}
```

## 📊 Pagination

### Récupérer avec pagination personnalisée

```bash
# Page 2, 20 éléments par page
curl "http://localhost:8000/api/referentiel/languages?page=2&per_page=20"

# Deuxième page, 50 éléments
curl "http://localhost:8000/api/referentiel/languages?page=2&per_page=50"
```

## 🎬 Cas d'usage complets

### Cas 1 : Créer puis récupérer une ville

```bash
# 1. Créer
curl -X POST http://localhost:8000/api/referentiel/cities \
  -H "Content-Type: application/json" \
  -d '{"nom": "Paris", "tag": "PARIS"}' \
  | jq '.data.id' # Récupérer l'ID

# 2. Récupérer (remplacer 1 par l'ID obtenu)
curl http://localhost:8000/api/referentiel/cities/1
```

### Cas 2 : Importer des nationalités

```bash
#!/bin/bash

# Données à importer
NATIONALITIES=(
  '{"nom":"Française","tag":"FR"}'
  '{"nom":"Belge","tag":"BE"}'
  '{"nom":"Allemande","tag":"DE"}'
)

# Importer chaque nationalité
for nationality in "${NATIONALITIES[@]}"; do
  curl -X POST http://localhost:8000/api/referentiel/nationalities \
    -H "Content-Type: application/json" \
    -d "$nationality"
done
```

### Cas 3 : Mettre à jour en masse

```bash
#!/bin/bash

# Récupérer tous les rôles
roles=$(curl -s http://localhost:8000/api/referentiel/roles | jq '.data[] | .id')

# Ajouter un préfixe à chaque rôle
for role_id in $roles; do
  curl -X PUT http://localhost:8000/api/referentiel/roles/$role_id \
    -H "Content-Type: application/json" \
    -d '{"tag":"ADMIN_ROLE"}'
done
```

## 🔍 Débogage

### Activer les logs détaillés

Modifiez `.env`:
```
APP_DEBUG=true
LOG_CHANNEL=single
```

### Vérifier les erreurs

```bash
# Voir les logs Laravel
tail -f storage/logs/laravel.log
```

## 🎯 Bonnes pratiques

1. **Toujours valider les entrées côté client avant envoi**
   ```javascript
   // Exemple JavaScript
   if (!nom || !tag) {
       console.error('Les champs nom et tag sont obligatoires');
       return;
   }
   ```

2. **Gérer les erreurs de l'API**
   ```javascript
   fetch('/api/referentiel/languages', {...})
       .then(res => res.json())
       .then(data => {
           if (!data.success) {
               console.error(data.errors);
           } else {
               // Traiter data.data
           }
       });
   ```

3. **Utiliser la pagination correctement**
   ```javascript
   // Charger les pages de façon fluide
   async function loadMore(page) {
       const response = await fetch(`/api/referentiel/languages?page=${page}&per_page=20`);
       const data = await response.json();
       return data.data;
   }
   ```

4. **Cacher les IDs sensibles si nécessaire**
   ```php
   // Dans le contrôleur, masquer l'ID
   $data = $resource->only(['nom', 'tag']);
   ```

## 📞 Support

Pour les problèmes ou questions :
1. Vérifiez la documentation API_DOCUMENTATION.md
2. Consultez les logs d'erreur
3. Vérifiez que les migrations sont exécutées
