# ⚙️ Configuration et Setup - Module Referentiel

## 🚀 Installation initiale

### 1. Vérifier l'activation du module

```bash
# Vérifier modules_statuses.json
cat modules_statuses.json

# Doit contenir:
# {
#   "Referentiel": true,
#   ...
# }
```

### 2. Exécuter les migrations

```bash
# Toutes les migrations
php artisan migrate

# Ou seulement le module Referentiel
php artisan migrate --path=Modules/Referentiel/Database/Migrations

# Voir l'état des migrations
php artisan migrate:status
```

### 3. Seeder les données (optionnel)

```bash
# Seeder tous les référentiels
php artisan db:seed --class=ReferentielDatabaseSeeder

# Ou seeder un spécifique
php artisan db:seed --class=LangueTableSeeder
```

### 4. Vérifier les permissions

```bash
# S'assurer que storage/ est inscriptible
chmod -R 775 storage/
chmod -R 775 bootstrap/cache/

# Sur Windows (avec Git Bash ou PowerShell)
icacls storage /grant:r "%USERNAME%:(F)" /t
```

## 📋 Configuration

### Variables d'environnement (.env)

Ajouter si nécessaire:

```env
# API
API_PREFIX=api
API_VERSION=v1

# Pagination
PAGINATION_DEFAULT=15
PAGINATION_MAX=100

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cvtheque
DB_USERNAME=root
DB_PASSWORD=
```

### Configuration d'application

Fichier: `config/app.php`

Vérifier que les providers sont enregistrés:

```php
'providers' => [
    // Laravel providers
    Illuminate\Auth\AuthServiceProvider::class,
    // ...
    
    // Nwidart NSWAG (pour les modules)
    Nwidart\Modules\LaravelModulesServiceProvider::class,
]
```

### Service Provider du module

Fichier: `Modules/Referentiel/Providers/ReferentielServiceProvider.php`

Vérifier que les routes sont chargées:

```php
public function boot()
{
    $this->registerTranslations();
    $this->registerConfig();
    $this->registerViews();
    $this->loadMigrationsFrom(module_path($this->moduleName, 'Database/Migrations'));
    $this->loadRoutesFrom(module_path($this->moduleName, 'Routes/api.php'));
}
```

## 🗄️ Base de données

### Migration manuelle (si nécessaire)

```bash
# Créer une migration
php artisan make:migration create_langues_table --path=Modules/Referentiel/Database/Migrations

# Puis éditer le fichier créé
```

### Vérifier les tables

```bash
# Via Tinker
php artisan tinker
> DB::table('langues')->count();
> DB::table('pays')->count();
```

### Réinitialiser les données

```bash
# Supprimer toutes les tables
php artisan migrate:reset

# Réexécuter toutes les migrations
php artisan migrate

# Repeupler avec les seeders
php artisan db:seed --class=ReferentielDatabaseSeeder
```

## 🧪 Tests de l'API

### 1. Vérifier que l'API est accessible

```bash
# Dans le terminal
curl http://localhost:8000/api/referentiel/languages

# Doit retourner un JSON avec le format:
# {
#   "success": true,
#   "data": [...],
#   "pagination": {...}
# }
```

### 2. Tester un endpoint POST

```bash
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -d '{"nom":"Français","tag":"FR"}'

# Doit retourner:
# {
#   "success": true,
#   "message": "Language created successfully",
#   "data": {...}
# }
```

### 3. Tester avec Postman

- Importer `postman_collection.json`
- Définir `base_url` dans l'onglet Variables
- Exécuter les requêtes

## 🐛 Débogage

### Activer les logs détaillés

```bash
# Ajouter à .env
APP_DEBUG=true
LOG_CHANNEL=single
LOG_LEVEL=debug

# Voir les logs
tail -f storage/logs/laravel.log
```

### Vérifier les erreurs courantes

#### 1. Route non trouvée (404)

```bash
# Vérifier que les routes sont enregistrées
php artisan route:list | grep referentiel

# Si vide, vérifier:
# 1. Que le module est activé
# 2. Que le ServiceProvider charge les routes
```

#### 2. Modèle non trouvé (class not found)

```bash
# Vérifier le namespace
# Les modèles doivent être dans: Modules\Referentiel\Entities\

# Vérifier l'autoload
composer dump-autoload
```

#### 3. Erreur de validation (422)

```bash
# Vérifier les règles dans le contrôleur
# Les champs obligatoires sont: nom, tag

# Tester avec des données complètes
curl -X POST http://localhost:8000/api/referentiel/languages \
  -H "Content-Type: application/json" \
  -d '{"nom":"Français","tag":"FR"}'
```

#### 4. CORS (Cross-Origin)

Si vous avez des erreurs CORS, ajouter à `.env`:

```env
CORS_ALLOWED_ORIGINS=*
```

Et dans `config/cors.php`:

```php
'allowed_origins' => ['*'],
'allowed_methods' => ['*'],
'allowed_headers' => ['*'],
```

## 🔧 Commandes utiles

### Gestion du module

```bash
# Lister les modules
php artisan module:list

# Activer le module
php artisan module:enable Referentiel

# Désactiver le module
php artisan module:disable Referentiel

# Créer un nouveau module
php artisan module:make NomModule
```

### Cache

```bash
# Vider le cache
php artisan cache:clear
php artisan config:clear
php artisan route:clear

# Reconstruire le cache
php artisan config:cache
php artisan route:cache
```

### Base de données

```bash
# Voir l'état des migrations
php artisan migrate:status

# Rollback dernière migration
php artisan migrate:rollback

# Rollback tout
php artisan migrate:reset

# Refresh (reset + migrate)
php artisan migrate:refresh

# Refresh + seed
php artisan migrate:refresh --seed
```

### Développement

```bash
# Démarrer le serveur
php artisan serve

# Mode debug
php artisan tinker

# Générer une clé d'application
php artisan key:generate
```

## 📊 Vérification des données

### Via Artisan Tinker

```bash
php artisan tinker

# Une fois dans tinker
>>> use Modules\Referentiel\Entities\Langue;
>>> Langue::all();
>>> Langue::count();
>>> Langue::find(1);
>>> Langue::create(['nom' => 'Anglais', 'tag' => 'EN']);
```

### Via base de données directe

```bash
# MySQL
mysql -u root -p cvtheque -e "SELECT * FROM langues;"

# PostgreSQL
psql cvtheque -c "SELECT * FROM langues;"

# SQLite
sqlite3 database.sqlite "SELECT * FROM langues;"
```

## 🚨 Checklist de déploiement

Avant le déploiement en production:

- [ ] Toutes les migrations sont exécutées
- [ ] Le module est activé dans `modules_statuses.json`
- [ ] Les tests passent
- [ ] Le cache est vidé
- [ ] Les erreurs de logs sont résolues
- [ ] Les permissions des fichiers sont correctes
- [ ] La base de données est seededée avec les données
- [ ] CORS est configuré correctement
- [ ] `.env` est configuré pour la production
- [ ] `APP_DEBUG=false` en production
- [ ] Les logs sont vérifiés: `tail -f storage/logs/laravel.log`

## 📞 Dépannage

### Mon API retourne 500

1. Vérifier les logs: `tail -f storage/logs/laravel.log`
2. Vérifier que le modèle existe: `Modules/Referentiel/Entities/Nom.php`
3. Vérifier que le service existe: `Modules/Referentiel/Services/NomService.php`
4. Vérifier que le contrôleur existe et injecte le service

### Ma migration ne fonctionne pas

```bash
# Vérifier que le fichier existe
ls Modules/Referentiel/Database/Migrations/

# Réexécuter la migration avec output détaillé
php artisan migrate --path=Modules/Referentiel/Database/Migrations -vvv
```

### Je ne vois pas les routes

```bash
# Lister les routes
php artisan route:list | grep referentiel

# Vider le cache des routes
php artisan route:clear
```

### Mon service n'injecte pas

Vérifier que le service a un constructeur vide ou que Laravel peut l'instancier automatiquement.

## 💡 Bonnes pratiques

1. **Toujours utiliser les services** plutôt que d'accéder directement aux modèles
2. **Valider les données** côté serveur et côté client
3. **Utiliser la pagination** pour les listes
4. **Logger les erreurs** pour le débogage
5. **Documenter le code** pour la maintenabilité
6. **Tester les endpoints** avant le déploiement

## 📚 Resources

- [Laravel Documentation](https://laravel.com/docs)
- [NSWAG Modules](https://nwidart.com/laravel-modules/)
- [Eloquent ORM](https://laravel.com/docs/eloquent)
- [API REST Best Practices](https://restfulapi.net/)

---

**Pour plus d'aide, consultez:**
- `README.md` - Overview du module
- `API_DOCUMENTATION.md` - Documentation API
- `USAGE_GUIDE.md` - Exemples d'utilisation
