# 📚 Module Referentiel - CVTheque

## 🎯 Overview

Le module **Referentiel** fournit une API RESTful complète pour gérer les données de référence du système CVTheque. Il inclut les civilités, langues, nationalités, pays, villes, niveaux d'études, permissions, rôles, et types de documents/contrats/travail.

## 📊 Architecture

### Stack technologique
- **Framework**: Laravel
- **Pattern**: Service + Repository
- **API**: RESTful JSON
- **Pagination**: Intégrée

### Structure des fichiers

```
Modules/Referentiel/
├── Entities/
│   ├── Civiliter.php
│   ├── Langue.php
│   ├── Nationalite.php
│   ├── Pays.php
│   ├── Ville.php
│   ├── NiveauEtude.php
│   ├── Permission.php
│   ├── Role.php
│   ├── TDocuments.php
│   ├── Tcontrat.php
│   ├── Ttravail.php
│   └── LangueCandidat.php
│
├── Services/
│   ├── BaseService.php          (Classe abstraite CRUD)
│   ├── CiviliterService.php
│   ├── LangueService.php
│   ├── NationaliteService.php
│   ├── PaysService.php
│   ├── VilleService.php
│   ├── NiveauEtudeService.php
│   ├── PermissionService.php
│   ├── RoleService.php
│   ├── TDocumentsService.php
│   ├── TcontratService.php
│   ├── TtravailService.php
│   └── LangueCandidatService.php
│
├── Http/Controllers/
│   ├── CiviliterController.php
│   ├── LangueController.php
│   ├── NationaliteController.php
│   ├── PaysController.php
│   ├── VilleController.php
│   ├── NiveauEtudeController.php
│   ├── PermissionController.php
│   ├── RoleController.php
│   ├── TDocumentsController.php
│   ├── TcontratController.php
│   ├── TtravailController.php
│   └── LangueCandidatController.php
│
├── Routes/
│   ├── api.php                  (120 endpoints)
│   └── web.php
│
├── Database/
│   ├── Migrations/              (12 migrations)
│   └── Seeders/
│
├── Resources/
├── Tests/
├── Config/
│
├── API_DOCUMENTATION.md         (Documentation complète)
├── USAGE_GUIDE.md              (Guide d'utilisation)
├── IMPLEMENTATION_SUMMARY.md   (Résumé technique)
├── postman_collection.json     (Collection Postman)
└── README.md                   (Ce fichier)
```

## 🚀 Démarrage rapide

### 1. Vérifier les migrations

```bash
# Dans le répertoire racine du projet Laravel
php artisan migrate

# Ou si vous utilisez une migration spécifique du module
php artisan migrate --path=Modules/Referentiel/Database/Migrations
```

### 2. Vérifier l'enregistrement du module

Assurez-vous que le module est activé dans `modules_statuses.json`:
```json
{
  "Referentiel": true
}
```

### 3. Tester l'API

```bash
# Test simple avec cURL
curl http://localhost:8000/api/referentiel/languages

# Avec Postman
# Importer le fichier postman_collection.json
```

## 📡 Endpoints disponibles

### Pattern RESTful standard

Pour chaque ressource, les endpoints suivants sont disponibles:

```
GET    /api/referentiel/{resource}              # Liste (paginée)
GET    /api/referentiel/{resource}/{id}         # Détail
POST   /api/referentiel/{resource}              # Créer
PUT    /api/referentiel/{resource}/{id}         # Mettre à jour
DELETE /api/referentiel/{resource}/{id}         # Supprimer
```

### Ressources disponibles (12)

- `/civilities` - Civilités
- `/languages` - Langues
- `/nationalities` - Nationalités
- `/countries` - Pays
- `/cities` - Villes
- `/education-levels` - Niveaux d'études
- `/permissions` - Permissions
- `/roles` - Rôles
- `/document-types` - Types de documents
- `/contract-types` - Types de contrats
- `/work-types` - Types de travail
- `/candidate-languages` - Langues des candidats

**Total: 60 endpoints (5 par ressource × 12 ressources)**

## 💼 Services

Chaque service hérite de **BaseService** qui fournit les méthodes CRUD:

```php
// Lecture
$service->getAll(perPage, page)          // Avec pagination
$service->getAllWithoutPagination()      // Sans pagination
$service->getById(id)                    // Par ID
$service->getBy(field, value)            // Recherche filtrée
$service->exists(id)                     // Vérifier existence
$service->count()                        // Compter

// Écriture
$service->create(data)                   // Créer
$service->update(id, data)               // Mettre à jour
$service->delete(id)                     // Supprimer
```

## 📝 Exemples d'utilisation

### En PHP (contrôleur)

```php
use Modules\Referentiel\Services\LangueService;

class MyController extends Controller
{
    public function __construct(private LangueService $langueService) {}

    public function example()
    {
        // Créer
        $langue = $this->langueService->create([
            'nom' => 'Français',
            'tag' => 'FR'
        ]);

        // Récupérer
        $all = $this->langueService->getAll(15, 1);
        $one = $this->langueService->getById(1);

        // Mettre à jour
        $this->langueService->update(1, ['nom' => 'Français']);

        // Supprimer
        $this->langueService->delete(1);
    }
}
```

### Via l'API REST (JavaScript)

```javascript
// Créer
const response = await fetch('/api/referentiel/languages', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ nom: 'Français', tag: 'FR' })
});
const data = await response.json();

// Récupérer
const list = await fetch('/api/referentiel/languages');
const items = await list.json();

// Mettre à jour
const update = await fetch('/api/referentiel/languages/1', {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ nom: 'Français' })
});

// Supprimer
const delete = await fetch('/api/referentiel/languages/1', {
    method: 'DELETE'
});
```

## 🔒 Sécurité

### Validations

Les validations suivantes s'appliquent lors de la création/modification:

```php
'nom'  => 'required|string|max:255',
'tag'  => 'required|string|max:50'
```

### Gestion des erreurs

```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "nom": ["The nom field is required."],
    "tag": ["The tag field is required."]
  }
}
```

### Codes HTTP

- `200 OK` - Succès (GET, PUT)
- `201 Created` - Ressource créée (POST)
- `404 Not Found` - Ressource inexistante
- `422 Unprocessable Entity` - Erreur de validation
- `500 Internal Server Error` - Erreur serveur

## 📚 Documentation complète

- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Documentation API détaillée
- **[USAGE_GUIDE.md](./USAGE_GUIDE.md)** - Guide d'utilisation avec exemples
- **[IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)** - Résumé technique
- **[postman_collection.json](./postman_collection.json)** - Collection Postman à importer

## 🧪 Tests

### Tester avec Postman

1. Télécharger [Postman](https://www.postman.com/)
2. Importer `postman_collection.json`
3. Définir la variable `base_url` = `http://localhost:8000`
4. Exécuter les requêtes

### Tester avec cURL

```bash
# Récupérer toutes les langues
curl http://localhost:8000/api/referentiel/languages

# Créer une langue
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -d '{"nom":"Français","tag":"FR"}'
```

## 🔄 Pagination

Tous les endpoints de liste supportent la pagination:

```
GET /api/referentiel/languages?page=1&per_page=15
```

### Paramètres

- `page` (défaut: 1) - Numéro de page
- `per_page` (défaut: 15) - Éléments par page

### Réponse

```json
{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "per_page": 15,
    "current_page": 1,
    "last_page": 7,
    "from": 1,
    "to": 15
  }
}
```

## 🛠️ Maintenance

### Ajouter une nouvelle ressource

1. Créer le modèle dans `Entities/`
2. Créer le service héritant de `BaseService` dans `Services/`
3. Créer le contrôleur dans `Http/Controllers/`
4. Ajouter les routes dans `Routes/api.php`

### Personnaliser un service

```php
// Dans ServiceNom.php
class NomService extends BaseService
{
    protected function getModel(): Model
    {
        return new Nom();
    }

    // Ajouter des méthodes personnalisées
    public function custom()
    {
        return $this->model->where('custom', true)->get();
    }
}
```

## 📦 Dépendances

- Laravel 8+
- PHP 7.4+
- Base de données (MySQL, PostgreSQL, SQLite, etc.)

## 📋 Checklist de déploiement

- [ ] Migrations exécutées
- [ ] Module activé dans `modules_statuses.json`
- [ ] Cache vidé: `php artisan cache:clear`
- [ ] Configuration vérifiée: `.env`
- [ ] Tests passés
- [ ] Documentation lue et comprise

## 🤝 Contribution

Pour améliorer le module:

1. Créer une branche feature
2. Implémenter les modifications
3. Ajouter les tests
4. Créer une pull request

## 📞 Support

Pour les questions ou problèmes:

1. Consulter la documentation
2. Vérifier les logs: `storage/logs/laravel.log`
3. Vérifier que les migrations sont à jour

## 📄 Licence

Propriétaire CVTheque

## 🎉 Merci!

Module créé avec ❤️ par l'équipe CVTheque
