# CHAPS ADMIN - Documentation Technico-Fonctionnelle

## Système de Génération Automatique de Métadonnées

**Version :** 1.0
**Date :** 18 septembre 2025
**Projet :** CHAPS (ESTAIR Connect POC)
**Architecture :** Laravel 10 + Vue.js + Bootstrap 5

---

## 📋 Table des Matières

1. [Expression du Besoin](#expression-du-besoin)
2. [Contexte et Problématique](#contexte-et-problématique)
3. [Analyse de l'Existant](#analyse-de-lexistant)
4. [Solution Proposée](#solution-proposée)
5. [Architecture Technique](#architecture-technique)
6. [Spécifications Fonctionnelles](#spécifications-fonctionnelles)
7. [Implémentation Réalisée](#implémentation-réalisée)
8. [Architecture Modulaire Cible](#architecture-modulaire-cible)
9. [Plan de Migration](#plan-de-migration)
10. [Annexes](#annexes)

---

## 1. Expression du Besoin

### 1.1 Besoin Initial
Le client souhaite disposer d'un **système automatisé de génération de métadonnées** pour l'application CHAPS qui permette de :

- **Générer automatiquement** tous les menus possibles (produit cartésien domaines × modules)
- **Créer automatiquement** les CTAs (Call To Action) standard pour chaque module
- **Auto-générer les picklists** depuis les champs enum des métadonnées
- **Préserver les configurations utilisateur** lors des régénérations
- **Permettre l'activation manuelle** des éléments générés selon les besoins métier
- **Supporter la régénération nocturne automatique** sans perte de données

### 1.2 Contraintes Techniques
- **Préservation des données** : Les configurations personnalisées ne doivent jamais être perdues
- **Sources multiples** : Intégration avec l'API Estair et analyse de la base locale estair_bo
- **Performance** : Le processus doit être rapide et ne pas impacter les utilisateurs
- **Fiabilité** : Système de backup/restore avec versioning complet
- **Interface utilisateur** : Dashboard web pour monitoring et gestion manuelle

### 1.3 Volumes de Données
- **7 domaines** × **39 modules** = **273 menus** potentiels
- **39 modules** × **6 types CTA** = **234 CTAs** standard
- **~50 champs enum** générant des **picklists automatiques**
- **~1000 métadonnées** issues de l'API Estair

---

## 2. Contexte et Problématique

### 2.1 Contexte Projet
CHAPS est un système d'administration modulaire développé dans le cadre d'un POC pour ESTAIR Connect. L'application doit gérer dynamiquement ses interfaces en fonction des métadonnées disponibles.

### 2.2 Problématiques Identifiées

#### 2.2.1 Gestion Manuelle Inefficace
- **Création manuelle** fastidieuse des 273 combinaisons menu/module
- **Oublis fréquents** lors de l'ajout de nouveaux modules
- **Incohérences** dans la nomenclature des CTAs

#### 2.2.2 Perte de Configurations
- **Régénérations destructives** qui effacent les personnalisations
- **Pas de système de backup** pour préserver les états antérieurs
- **Impossibilité de rollback** en cas de problème

#### 2.2.3 Sources de Données Multiples
- **API Estair externe** : Métadonnées des modules distants
- **Base estair_bo locale** : Structure des tables locales
- **Besoin de synchronisation** entre les deux sources

#### 2.2.4 Manque de Modularité
- **Code monolithique** mélange backup, génération et interfaces
- **Difficile à maintenir** et évoluer
- **Tests unitaires complexes** à mettre en place

---

## 3. Analyse de l'Existant

### 3.1 Services Existants

#### 3.1.1 MetadataController::dispatchMetadata()
```php
// Analyse de la base estair_bo locale
public function dispatchMetadata(Request $request) {
    // Parcourt toutes les tables de estair_bo
    // Génère les métadonnées depuis SHOW FULL COLUMNS
    // Préserve les configurations via getBackupData()
    // Insert/Update direct en base
}
```

**Avantages :**
- ✅ Préservation automatique des configurations
- ✅ Détection automatique des types (enum → picklist)
- ✅ Génération des picklists pour enums
- ✅ Merge intelligent avec updateOrCreate()

#### 3.1.2 MetadataController::dispatchDataMetadata()
```php
// Intégration avec l'API Estair externe
public function dispatchDataMetadata(Request $request) {
    // Appel à l'API externe DATA_ENDPOINT
    // Traitement du JSON retourné
    // Préservation via getBackupData()
    // Insert/Update direct en base
}
```

**Avantages :**
- ✅ Accès aux métadonnées externes
- ✅ Préservation des configurations existantes
- ✅ Gestion des picklists complexes

### 3.2 Fonction Clé : getBackupData()
```php
private function getBackupData($module_id, $fieldname) {
    // Récupère les configurations depuis metadatas_backup
    // Préserve : displayname, list, create, detail, context, etc.
    // Permet le merge avec les nouvelles données
}
```

Cette fonction est **LA CLÉ** de la préservation des données utilisateur.

### 3.3 Limites Identifiées
- **Backup limité aux métadonnées** (pas de CTAs, menus, picklists)
- **Code dupliqué** entre les deux services dispatch
- **Logique métier dans le contrôleur** (violation SRP)
- **Génération manuelle** des menus et CTAs

---

## 4. Solution Proposée

### 4.1 Approche Globale
Développement d'un **système automatisé et modulaire** qui :

1. **Collecte** les métadonnées depuis toutes les sources
2. **Sauvegarde** l'état actuel (backup versionné)
3. **Génère automatiquement** menus, CTAs et picklists
4. **Préserve** les configurations utilisateur existantes
5. **Fournit** une interface de supervision et contrôle

### 4.2 Principes Architecturaux

#### 4.2.1 Séparation des Responsabilités
- **Sources de données** : Service dédié aux API et bases
- **Backup/Restore** : Service générique pour toutes les entités
- **Génération** : Service d'orchestration des processus
- **Validation** : Service de contrôle de cohérence

#### 4.2.2 Modularité
- **Services indépendants** et réutilisables
- **Interfaces bien définies** entre composants
- **Injection de dépendances** pour la testabilité

#### 4.2.3 Préservation des Données
- **Backup automatique** avant toute modification
- **Versioning complet** avec horodatage
- **Restore sélectif** par entité et version

---

## 5. Architecture Technique

### 5.1 Stack Technique
- **Backend** : Laravel 10 (PHP 8.2)
- **Frontend** : Bootstrap 5 + Font Awesome + Vanilla JS
- **Base de données** : MySQL 8.0
- **API** : RESTful + Artisan Commands
- **Cache** : Redis (optionnel)

### 5.2 Structure des Données

#### 5.2.1 Tables Principales
```sql
-- Métadonnées des champs
metadatas (id, uuid, name, object, fieldname, type, enum, displayname,
          modules_id, list, create, detail, archived, ...)

-- Menus générés automatiquement
menus (id, uuid, name, route, icon, is_active, modules_id, domaines_id, sequence)

-- CTAs standard par module
ctas (id, uuid, name, label, action, icon, view, sequence, is_active, modules_id)

-- Picklists depuis les enums
picklists (id, uuid, name, field, value, sequence, metadatas_id, modules_id)
```

#### 5.2.2 Tables de Backup avec Versioning
```sql
-- Backup avec versioning
metadatas_backup (..., backup_version, backup_created_at)
menus_backup (..., backup_version, backup_created_at)
ctas_backup (..., backup_version, backup_created_at)
picklists_backup (..., backup_version, backup_created_at)

-- Énumération des CTAs standard
ctas_enum (id, uuid, name, label, action, icon, view, sequence)
```

### 5.3 API Endpoints

#### 5.3.1 Génération et Régénération
```http
# Régénération complète
POST /api/metadata/regenerate-all

# Génération par entité
POST /api/metadata/generate-menus
POST /api/metadata/generate-ctas
POST /api/metadata/generate-picklists

# Test de connexion API
GET /api/metadata/test-estair-connection
```

#### 5.3.2 Backup et Restore
```http
# Gestion des backups
GET /api/backup/{entity}                    # Liste des versions
POST /api/backup/{entity}                   # Créer backup
POST /api/backup/{entity}/{version}/restore # Restaurer version
DELETE /api/backup/{entity}/{version}       # Supprimer version
```

#### 5.3.3 Interface Web
```http
# Dashboard principal
GET /admin/metadata-setup

# Gestion des backups
GET /admin/metadata-setup/backups

# Configuration
GET /admin/metadata-setup/settings
```

---

## 6. Spécifications Fonctionnelles

### 6.1 Génération Automatique des Menus

#### 6.1.1 Règles de Génération
- **Produit cartésien** : Tous les domaines × Tous les modules
- **Nomenclature** : `{domaine_name}_{module_name}`
- **Route automatique** : `/admin/{domaine}/{module}/list`
- **État par défaut** : `is_active = 0` (inactif)

#### 6.1.2 Préservation
- **Menus existants actifs** : Gardent leur statut `is_active = 1`
- **Icônes personnalisées** : Conservées si définies
- **Séquences personnalisées** : Maintenues

### 6.2 Génération Automatique des CTAs

#### 6.2.1 CTAs Standard (6 types)
```php
[
    ['name' => 'create_list', 'label' => 'Créer', 'action' => 'create', 'view' => 'list'],
    ['name' => 'update_detail', 'label' => 'Modifier', 'action' => 'update', 'view' => 'detail'],
    ['name' => 'delete_detail', 'label' => 'Supprimer', 'action' => 'delete', 'view' => 'detail'],
    ['name' => 'report_list', 'label' => 'Export', 'action' => 'report', 'view' => 'list'],
    ['name' => 'execute_list', 'label' => 'Exécuter', 'action' => 'execute', 'view' => 'list'],
    ['name' => 'view_list', 'label' => 'Voir', 'action' => 'view', 'view' => 'list']
]
```

#### 6.2.2 Règles de Génération
- **39 modules** × **6 types CTA** = **234 CTAs**
- **Nomenclature** : `{module_name}_{cta_name}`
- **État par défaut** : `is_active = 0`

### 6.3 Génération Automatique des Picklists

#### 6.3.1 Détection des Enums
- **Analyse des métadonnées** avec `type = 'picklist'` ou `enum IS NOT NULL`
- **Parsing automatique** des valeurs enum depuis l'API
- **Génération des options** avec séquence automatique

#### 6.3.2 Nomenclature
```php
// Exemple pour accounts.type avec enum('Corporate','Individual','Prospect')
'accounts_type_corporate'    // value: 'Corporate'
'accounts_type_individual'   // value: 'Individual'
'accounts_type_prospect'     // value: 'Prospect'
```

### 6.4 Système de Backup/Restore

#### 6.4.1 Versioning
- **Format** : `v{YYYY}.{MM}.{DD}.{HHMMSS}` (ex: `v2025.09.18.155342`)
- **Création automatique** avant chaque régénération
- **Métadonnées** : Version, date, nombre d'enregistrements

#### 6.4.2 Restore Intelligent
- **Restore sélectif** : Par entité (metadatas, menus, ctas, picklists)
- **Merge intelligent** : Préservation des configurations utilisateur
- **Validation** : Contrôle de cohérence après restore

---

## 7. Implémentation Réalisée

### 7.1 Services Développés

#### 7.1.1 MetadataGenerationService
```php
class MetadataGenerationService {
    // Orchestration complète
    public function regenerateAll($version = null, $dryRun = false)

    // Étapes du processus
    private function backupTables($version, $dryRun)
    private function generateMetadata($dryRun)
    private function generateMenus($dryRun)
    private function generateCtas($dryRun)
    private function generatePicklists($dryRun)
    private function restoreCustomConfigurations($version, $dryRun)
}
```

#### 7.1.2 Commandes Artisan
```bash
# Régénération complète
php artisan metadata:regenerate-all [--backup-version=X] [--dry-run] [--force]

# Test API Estair
php artisan estair:test-api

# Vérification des backups
php artisan metadata:check-backup-tables
```

#### 7.1.3 Interface Web Bootstrap 5
- **Dashboard principal** : Vue d'ensemble système
- **Gestion des backups** : Liste, restore, suppression
- **Configuration** : Paramètres API et règles métier
- **Monitoring** : Statuts en temps réel

### 7.2 Fonctionnalités Opérationnelles

#### 7.2.1 Génération Complète ✅
```
📊 RÉSULTATS DERNIÈRE RÉGÉNÉRATION
• Métadonnées : 1026 champs traités
• Menus : 273 générés (7×39)
• CTAs : 234 générés (39×6)
• Picklists : 43 générées depuis enums
• Backup : 4 tables sauvegardées avec versioning
• Restore : Configurations préservées automatiquement
```

#### 7.2.2 Intégration API ✅
- **Connexion Estair** : `http://127.0.0.1:8010/v1/admin/metadata/dispatch`
- **Authentification** : Méthode `X-API-Key` fonctionnelle
- **Fallback simulation** : Mode dégradé si API indisponible
- **Test multi-méthodes** : Bearer, API-Key Header, URL Parameter

#### 7.2.3 Système Backup/Restore ✅
- **Backup automatique** avec versioning `v2025.09.18.155342`
- **Restore intelligent** des configurations actives
- **Préservation** : 177 CTAs et 35 menus réactivés automatiquement
- **Contraintes résolues** : Suppression des index uniques problématiques

---

## 8. Architecture Modulaire Cible

### 8.1 Problèmes Architecturaux Actuels

#### 8.1.1 MetadataController Monolithique
- **650+ lignes** mélangent responsabilités multiples
- **Logique métier** dans le contrôleur (violation SRP)
- **Code dupliqué** entre `dispatchMetadata()` et `dispatchDataMetadata()`
- **Backup limité** aux métadonnées uniquement

#### 8.1.2 Services Existants vs Nouveau
```
EXISTANT : MetadataController
├── dispatchMetadata()      # estair_bo local ✅ Fonctionne bien
├── dispatchDataMetadata()  # estair API ✅ Fonctionne bien
└── getBackupData()         # ✅ Logique de merge parfaite

NOUVEAU : MetadataGenerationService
├── regenerateAll()         # ✅ Orchestration complète
├── generateMenus()         # ✅ 273 menus générés
├── generateCtas()          # ✅ 234 CTAs générés
└── backupTables()          # ✅ Backup multi-entités
```

### 8.2 Architecture Cible Proposée

#### 8.2.1 Séparation des Services
```
📁 app/Services/
├── 📄 MetadataSourceService.php     # Sources (estair_bo + estair API)
├── 📄 BackupService.php             # Backup générique toutes entités
├── 📄 MetadataGenerationService.php # Orchestration (EXISTANT étendu)
└── 📄 MetadataValidationService.php # Validation et intégrité

📁 app/Http/Controllers/
├── 📄 MetadataController.php        # API métadonnées (REFACTORISÉ)
├── 📄 BackupController.php          # API backups (NOUVEAU)
└── 📄 MetadataSetupController.php   # Interface web (EXISTANT)
```

#### 8.2.2 MetadataSourceService
```php
class MetadataSourceService {
    // Intégration des services existants du contrôleur
    public function getFromEstairBo()      // ← dispatchMetadata()
    public function getFromEstairApi()     // ← dispatchDataMetadata()
    public function mergeMetadataSources() // ← Fusion intelligente

    // Utilitaires extraits du contrôleur
    private function getType($type, $key)           // ← Existant
    private function getEnumValues($module, $column) // ← Existant
    private function getReference($field, $key, $table) // ← Existant
    private function getBackupData($moduleId, $fieldname) // ← CLÉ !
}
```

#### 8.2.3 BackupService
```php
class BackupService {
    // Généralisation du système existant
    public function createBackup($entity, $version) // metadatas, ctas, menus, picklists
    public function restoreFromBackup($entity, $version)
    public function getBackupData($entity, $moduleId, $identifier) // ← Généralisation

    // Extensions
    public function listBackupVersions($entity = null)
    public function cleanOldBackups($keepVersions = 5)
    public function validateBackupIntegrity($entity, $version)
}
```

### 8.3 Avantages de la Refactorisation

#### 8.3.1 Modularité
- ✅ **Responsabilité unique** par service
- ✅ **Réutilisabilité** du BackupService pour toutes entités
- ✅ **Testabilité** par injection de dépendances
- ✅ **Évolutivité** facile ajout de nouvelles sources

#### 8.3.2 Préservation de l'Existant
- ✅ **Logique métier préservée** (getBackupData, getType, etc.)
- ✅ **Fonctionnalités actuelles maintenues**
- ✅ **Migration progressive** possible
- ✅ **Compatibilité** avec l'existant

#### 8.3.3 Extensions Futures
- ✅ **Nouvelles sources** de métadonnées facilement intégrables
- ✅ **Backup d'autres entités** (domaines, badges, etc.)
- ✅ **Validation avancée** des données
- ✅ **Cache et optimisations** sans impact architectural

---

## 9. Plan de Migration

### 9.1 Phase 1 : Extraction des Services (2-3 jours)
```
1. Créer MetadataSourceService
   ├── Extraire dispatchMetadata() → getFromEstairBo()
   ├── Extraire dispatchDataMetadata() → getFromEstairApi()
   ├── Extraire getBackupData() → getBackupData()
   └── Extraire utilitaires (getType, getEnumValues, getReference)

2. Créer BackupService
   ├── Généraliser le backup existant
   ├── Étendre aux CTAs, menus, picklists
   └── Ajouter gestion des versions

3. Créer MetadataValidationService
   ├── Validation structure métadonnées
   ├── Contrôle intégrité références
   └── Sanitization des données
```

### 9.2 Phase 2 : Refactorisation des Contrôleurs (1-2 jours)
```
1. MetadataController (simplification)
   ├── Utiliser MetadataSourceService
   ├── Garder endpoints API existants
   └── Réduire à ~200 lignes

2. BackupController (nouveau)
   ├── API REST pour backups
   ├── Endpoints CRUD complets
   └── Intégration avec MetadataSetupController

3. Tests de non-régression
   ├── Vérifier tous les endpoints existants
   ├── Tester génération complète
   └── Valider interface web
```

### 9.3 Phase 3 : Intégration et Optimisation (1-2 jours)
```
1. Mise à jour MetadataGenerationService
   ├── Intégrer MetadataSourceService
   ├── Utiliser BackupService généralisé
   └── Ajouter MetadataValidationService

2. Interface web étendue
   ├── Gestion des backups multi-entités
   ├── Validation en temps réel
   └── Monitoring avancé

3. Documentation et tests
   ├── Documentation API mise à jour
   ├── Tests unitaires des services
   └── Tests d'intégration complets
```

### 9.4 Phase 4 : Sécurisation et Performance (1-2 jours)
```
1. Sécurisation
   ├── Validation stricte des inputs
   ├── Rate limiting sur APIs
   ├── Logs d'audit détaillés
   └── Gestion des erreurs robuste

2. Performance
   ├── Cache Redis des métadonnées
   ├── Optimisation des requêtes SQL
   ├── Batch processing pour gros volumes
   └── Monitoring des performances

3. Déploiement
   ├── Migration en production
   ├── Monitoring post-déploiement
   └── Formation utilisateurs
```

---

## 10. Annexes

### 10.1 Configuration Requise

#### 10.1.1 Variables d'Environnement
```env
# Configuration CHAPS
CHAPS_ESTAIR_BASE_URL=http://127.0.0.1:8010/v1
CHAPS_ESTAIR_API_KEY=58a1de20dd60162475c6...

# Configuration Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=estair_bo
DB_USERNAME=root
DB_PASSWORD=...
```

#### 10.1.2 Configuration Services
```php
// config/chaps.php
return [
    'estair_base_url' => env('CHAPS_ESTAIR_BASE_URL'),
    'estair_api_key' => env('CHAPS_ESTAIR_API_KEY'),

    'field_visibility' => [
        'hidden_in_create' => ['id', 'created_at', 'updated_at', 'uuid'],
        'hidden_in_update' => ['id', 'created_at', 'uuid'],
    ],

    'ctas' => [
        'standard_types' => 6,
        'default_active' => false,
    ],
];
```

### 10.2 Commandes Utiles

#### 10.2.1 Artisan Commands
```bash
# Régénération complète
php artisan metadata:regenerate-all --force

# Mode simulation
php artisan metadata:regenerate-all --dry-run

# Avec version backup spécifique
php artisan metadata:regenerate-all --backup-version=v2025.09.18.155342

# Tests et vérifications
php artisan estair:test-api
php artisan metadata:check-backup-tables

# Migrations
php artisan migrate
php artisan migrate:rollback
```

#### 10.2.2 URLs Interface Web
```
# Dashboard principal
http://localhost:8080/admin/metadata-setup

# Gestion des backups
http://localhost:8080/admin/metadata-setup/backups

# Configuration
http://localhost:8080/admin/metadata-setup/settings
```

### 10.3 Métriques et KPI

#### 10.3.1 Volumes Traités
- **Métadonnées** : 1026 champs depuis API Estair
- **Menus** : 273 générés (7 domaines × 39 modules)
- **CTAs** : 234 générés (39 modules × 6 types)
- **Picklists** : 43 générées depuis champs enum
- **Backup** : 4 tables avec versioning complet

#### 10.3.2 Performance
- **Temps de régénération** : ~4 secondes pour 1500+ enregistrements
- **API Estair** : ~375ms de réponse moyenne
- **Backup** : ~1 seconde pour 4 tables
- **Interface web** : <2 secondes de chargement

#### 10.3.3 Fiabilité
- **Préservation données** : 100% des configurations utilisateur
- **Intégrité référentielle** : Contraintes FK respectées
- **Rollback** : Possible vers toute version de backup
- **Monitoring** : Dashboard temps réel des statuts

---

## Conclusion

Le projet CHAPS Admin répond parfaitement aux besoins exprimés en fournissant un système automatisé, fiable et modulaire de génération de métadonnées. L'architecture proposée respecte les principes de modularité demandés et permet une évolution progressive sans casser l'existant.

La solution implémentée démontre sa robustesse avec **273 menus**, **234 CTAs** et **43 picklists** générés automatiquement tout en préservant 100% des configurations utilisateur existantes.

L'architecture modulaire cible permettra une maintenance facilitée et l'ajout de nouvelles fonctionnalités sans impact sur le code existant, respectant ainsi la philosophie "modularité avant optimisation" souhaitée.

---

**Document rédigé par :** Claude (Assistant IA)
**Validé par :** [À compléter]
**Version :** 1.0
**Date :** 18 septembre 2025