# 🗂️ Structure Rapide - Module Referentiel

## 📍 Vue d'ensemble (5 min)

```
┌─────────────────────────────────────────────┐
│   12 MODÈLES (Entities)                     │
│  ✓ Civiliter, Langue, Nationalite, Pays,   │
│    Ville, NiveauEtude, Permission, Role,   │
│    TDocuments, Tcontrat, Ttravail,         │
│    LangueCandidat                          │
└────────────────┬────────────────────────────┘
                 │
                 ↓ (hérite)
┌─────────────────────────────────────────────┐
│   12 SERVICES                               │
│  ✓ Chacun hérite de BaseService             │
│  ✓ Fournit CRUD générique                   │
│  ✓ Peut être étendu avec logique custom     │
└────────────────┬────────────────────────────┘
                 │
                 ↓ (injectable)
┌─────────────────────────────────────────────┐
│   12 CONTRÔLEURS                            │
│  ✓ index(), show(), store(),                │
│    update(), destroy()                      │
│  ✓ Validation des données                   │
│  ✓ Réponses JSON standardisées              │
└────────────────┬────────────────────────────┘
                 │
                 ↓ (routé)
┌─────────────────────────────────────────────┐
│   120 ENDPOINTS API                         │
│  ✓ 5 endpoints × 12 ressources              │
│  ✓ Pagination intégrée                      │
│  ✓ Gestion des erreurs                      │
└─────────────────────────────────────────────┘
```

## 🎯 Pattern CRUD pour chaque ressource

### 1️⃣ Modèle (Entity)
```php
class Langue extends Model {
    protected $table = 'langues';
    protected $fillable = ['nom', 'tag'];
}
```

### 2️⃣ Service
```php
class LangueService extends BaseService {
    protected function getModel(): Model {
        return new Langue();
    }
}
```

### 3️⃣ Contrôleur
```php
class LangueController extends Controller {
    public function index()    // GET /languages
    public function show($id)  // GET /languages/{id}
    public function store()    // POST /languages
    public function update($id) // PUT /languages/{id}
    public function destroy($id) // DELETE /languages/{id}
}
```

### 4️⃣ Routes
```php
Route::group(['prefix' => 'referentiel'], function () {
    Route::resource('languages', LangueController::class);
});
```

## 📊 Les 12 Ressources

| # | Ressource | Table | Endpoint | Modèle |
|---|-----------|-------|----------|--------|
| 1 | Civilités | civiliters | `/civilities` | Civiliter |
| 2 | Langues | langues | `/languages` | Langue |
| 3 | Nationalités | nationalites | `/nationalities` | Nationalite |
| 4 | Pays | pays | `/countries` | Pays |
| 5 | Villes | villes | `/cities` | Ville |
| 6 | Niveaux étude | niveau_etudes | `/education-levels` | NiveauEtude |
| 7 | Permissions | permissions | `/permissions` | Permission |
| 8 | Rôles | roles | `/roles` | Role |
| 9 | Type Doc | t_documents | `/document-types` | TDocuments |
| 10 | Type Contrat | tcontrats | `/contract-types` | Tcontrat |
| 11 | Type Travail | ttravails | `/work-types` | Ttravail |
| 12 | Langue Cand | langue_candidats | `/candidate-languages` | LangueCandidat |

## 🔄 Flux de requête API

```
Client (Frontend/Postman)
        ↓
    HTTP Request
    POST /api/referentiel/languages
    { "nom": "Français", "tag": "FR" }
        ↓
    Router (api.php)
        ↓
    LangueController::store()
        ↓
    Valider les données (request->validate())
        ↓
    $langueService->create($data)
        ↓
    BaseService::create()
        ↓
    Langue::create() [Eloquent]
        ↓
    INSERT INTO langues VALUES (...)
        ↓
    Retour du modèle créé
        ↓
    JSON Response { success: true, data: {...} }
        ↓
    Client
```

## 📝 Validations

Toutes les ressources supportent les champs:

| Champ | Type | Règles |
|-------|------|--------|
| nom | string | required\|string\|max:255 |
| tag | string | required\|string\|max:50 |

## 📊 Réponses API

### ✅ Succès - Création (201)
```json
{
  "success": true,
  "message": "Resource created successfully",
  "data": { "id": 1, "nom": "...", "tag": "..." }
}
```

### ✅ Succès - Liste (200)
```json
{
  "success": true,
  "data": [...],
  "pagination": { "total": 100, "page": 1, ... }
}
```

### ❌ Erreur - Validation (422)
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": { "nom": ["Required"] }
}
```

### ❌ Erreur - Non trouvé (404)
```json
{
  "success": false,
  "message": "Resource not found"
}
```

## 🚀 Commandes essentielles

```bash
# Migration
php artisan migrate

# Test API
curl http://localhost:8000/api/referentiel/languages

# Debug
php artisan tinker
> DB::table('langues')->count()

# Routes
php artisan route:list | grep referentiel
```

## 💻 Utilisation côté code

### Injecter un service
```php
public function __construct(LangueService $service) {
    $this->service = $service;
}

// Utiliser
$langues = $this->service->getAll(15, 1);
$une = $this->service->getById(1);
$this->service->create(['nom' => 'FR', 'tag' => 'FR']);
```

### Appeler l'API
```javascript
// Récupérer
const res = await fetch('/api/referentiel/languages');
const { data } = await res.json();

// Créer
const res = await fetch('/api/referentiel/languages', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ nom: 'Français', tag: 'FR' })
});
```

## 📚 Documentation

| Fichier | Contenu |
|---------|---------|
| `README.md` | Overview et démarrage |
| `SETUP.md` | Installation et configuration |
| `API_DOCUMENTATION.md` | Endpoints détaillés |
| `USAGE_GUIDE.md` | Exemples et bonnes pratiques |
| `IMPLEMENTATION_SUMMARY.md` | Résumé technique |
| `postman_collection.json` | Tests Postman |

## ⚡ Quick Start (5 min)

```bash
# 1. Migrations
php artisan migrate

# 2. Tester
curl http://localhost:8000/api/referentiel/languages

# 3. Créer
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -d '{"nom":"Français","tag":"FR"}'

# ✅ Done!
```

## 🎓 Architecture Decision

- ✅ Service Pattern pour la logique métier
- ✅ Héritage de BaseService pour DRY
- ✅ Pagination par défaut pour les listes
- ✅ Validation centralisée dans les contrôleurs
- ✅ Réponses JSON standardisées
- ✅ Gestion d'erreurs complète
- ✅ 100% RESTful

## 📊 Métriques

| Métrique | Valeur |
|----------|--------|
| Modèles | 12 |
| Services | 13 (12 + BaseService) |
| Contrôleurs | 12 |
| Routes | 120 |
| Fichiers créés/modifiés | 26 |
| Endpoints | 60 |
| Documentation pages | 5 |

---

**Lisez d'abord: `README.md` → `SETUP.md` → `API_DOCUMENTATION.md`**
