# Documentation API - Module Referentiel

## 📋 Vue d'ensemble

Ce module fournit une API RESTful complète pour gérer les données de référentiel du système CVTheque.

## 🔌 Endpoints disponibles

Tous les endpoints sont préfixés par `/api/referentiel`

### Civilities (Civilités)
- `GET /civilities` - Récupérer la liste paginée des civilités
- `GET /civilities/{id}` - Récupérer une civilité spécifique
- `POST /civilities` - Créer une nouvelle civilité
- `PUT /civilities/{id}` - Mettre à jour une civilité
- `DELETE /civilities/{id}` - Supprimer une civilité

### Languages (Langues)
- `GET /languages` - Récupérer la liste paginée des langues
- `GET /languages/{id}` - Récupérer une langue spécifique
- `POST /languages` - Créer une nouvelle langue
- `PUT /languages/{id}` - Mettre à jour une langue
- `DELETE /languages/{id}` - Supprimer une langue

### Nationalities (Nationalités)
- `GET /nationalities` - Récupérer la liste paginée des nationalités
- `GET /nationalities/{id}` - Récupérer une nationalité spécifique
- `POST /nationalities` - Créer une nouvelle nationalité
- `PUT /nationalities/{id}` - Mettre à jour une nationalité
- `DELETE /nationalities/{id}` - Supprimer une nationalité

### Countries (Pays)
- `GET /countries` - Récupérer la liste paginée des pays
- `GET /countries/{id}` - Récupérer un pays spécifique
- `POST /countries` - Créer un nouveau pays
- `PUT /countries/{id}` - Mettre à jour un pays
- `DELETE /countries/{id}` - Supprimer un pays

### Cities (Villes)
- `GET /cities` - Récupérer la liste paginée des villes
- `GET /cities/{id}` - Récupérer une ville spécifique
- `POST /cities` - Créer une nouvelle ville
- `PUT /cities/{id}` - Mettre à jour une ville
- `DELETE /cities/{id}` - Supprimer une ville

### Education Levels (Niveaux d'études)
- `GET /education-levels` - Récupérer la liste paginée des niveaux
- `GET /education-levels/{id}` - Récupérer un niveau spécifique
- `POST /education-levels` - Créer un nouveau niveau
- `PUT /education-levels/{id}` - Mettre à jour un niveau
- `DELETE /education-levels/{id}` - Supprimer un niveau

### Permissions
- `GET /permissions` - Récupérer la liste paginée des permissions
- `GET /permissions/{id}` - Récupérer une permission spécifique
- `POST /permissions` - Créer une nouvelle permission
- `PUT /permissions/{id}` - Mettre à jour une permission
- `DELETE /permissions/{id}` - Supprimer une permission

### Roles
- `GET /roles` - Récupérer la liste paginée des rôles
- `GET /roles/{id}` - Récupérer un rôle spécifique
- `POST /roles` - Créer un nouveau rôle
- `PUT /roles/{id}` - Mettre à jour un rôle
- `DELETE /roles/{id}` - Supprimer un rôle

### Document Types (Types de documents)
- `GET /document-types` - Récupérer la liste paginée des types
- `GET /document-types/{id}` - Récupérer un type spécifique
- `POST /document-types` - Créer un nouveau type
- `PUT /document-types/{id}` - Mettre à jour un type
- `DELETE /document-types/{id}` - Supprimer un type

### Contract Types (Types de contrats)
- `GET /contract-types` - Récupérer la liste paginée des types
- `GET /contract-types/{id}` - Récupérer un type spécifique
- `POST /contract-types` - Créer un nouveau type
- `PUT /contract-types/{id}` - Mettre à jour un type
- `DELETE /contract-types/{id}` - Supprimer un type

### Work Types (Types de travail)
- `GET /work-types` - Récupérer la liste paginée des types
- `GET /work-types/{id}` - Récupérer un type spécifique
- `POST /work-types` - Créer un nouveau type
- `PUT /work-types/{id}` - Mettre à jour un type
- `DELETE /work-types/{id}` - Supprimer un type

### Candidate Languages (Langues des candidats)
- `GET /candidate-languages` - Récupérer la liste paginée
- `GET /candidate-languages/{id}` - Récupérer une entrée spécifique
- `POST /candidate-languages` - Créer une nouvelle entrée
- `PUT /candidate-languages/{id}` - Mettre à jour une entrée
- `DELETE /candidate-languages/{id}` - Supprimer une entrée

## 📤 Format des données

### Créer/Mettre à jour une ressource

```json
{
  "nom": "Exemple",
  "tag": "EXEMPLE"
}
```

### Réponse de succès (201 Created)
```json
{
  "success": true,
  "message": "Resource created successfully",
  "data": {
    "id": 1,
    "nom": "Exemple",
    "tag": "EXEMPLE",
    "created_at": "2026-06-06T19:02:14.000000Z",
    "updated_at": "2026-06-06T19:02:14.000000Z"
  }
}
```

### Réponse de succès avec pagination (200 OK)
```json
{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "per_page": 15,
    "current_page": 1,
    "last_page": 7,
    "from": 1,
    "to": 15
  }
}
```

### Erreur de validation (422 Unprocessable Entity)
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "nom": ["The nom field is required."],
    "tag": ["The tag field is required."]
  }
}
```

### Ressource non trouvée (404 Not Found)
```json
{
  "success": false,
  "message": "Resource not found"
}
```

## 📊 Pagination

La pagination est activée par défaut avec 15 éléments par page.

### Paramètres de requête
- `page` (int) - Numéro de page (défaut: 1)
- `per_page` (int) - Éléments par page (défaut: 15)

```
GET /api/referentiel/languages?page=2&per_page=20
```

## 🏗️ Architecture

### Structure du module

```
Modules/Referentiel/
├── Entities/           # Modèles Eloquent
├── Services/           # Logique métier
│   ├── BaseService.php       # Classe abstraite commune
│   ├── CiviliterService.php  # Service Civilité
│   ├── LangueService.php     # Service Langue
│   └── ...
├── Http/
│   ├── Controllers/    # Contrôleurs API
│   │   ├── CiviliterController.php
│   │   ├── LangueController.php
│   │   └── ...
│   └── Requests/       # Form Requests (validations)
├── Routes/
│   └── api.php         # Routes API
└── Database/
    ├── Migrations/     # Migrations
    └── Seeders/        # Seeders
```

### Pattern de service

Chaque service hérite de `BaseService` qui fournit :
- `getAll(perPage, page)` - Récupérer avec pagination
- `getAllWithoutPagination()` - Récupérer tous les enregistrements
- `getById(id)` - Récupérer par ID
- `create(data)` - Créer un nouvel enregistrement
- `update(id, data)` - Mettre à jour
- `delete(id)` - Supprimer
- `getBy(field, value)` - Rechercher par champ
- `exists(id)` - Vérifier l'existence
- `count()` - Compter les enregistrements

## ✅ Validations

Les validations suivantes s'appliquent à toutes les ressources :
- `nom` : requis, string, max 255 caractères
- `tag` : requis, string, max 50 caractères

## 🎯 Exemples d'utilisation

### Créer une langue
```bash
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Français",
    "tag": "FR"
  }'
```

### Récupérer toutes les langues (page 1)
```bash
curl http://localhost:8000/api/referentiel/languages
```

### Récupérer une langue spécifique
```bash
curl http://localhost:8000/api/referentiel/languages/1
```

### Mettre à jour une langue
```bash
curl -X PUT http://localhost:8000/api/referentiel/languages/1 \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Français (mis à jour)",
    "tag": "FR_UPD"
  }'
```

### Supprimer une langue
```bash
curl -X DELETE http://localhost:8000/api/referentiel/languages/1
```

## 📝 Notes

- Tous les endpoints retournent du JSON
- Les timestamps sont au format ISO 8601
- Les erreurs incluent les codes HTTP appropriés
- La validation se fait côté serveur
