# Module de Gestion des Clients

## 📋 Vue d'ensemble

Le module de gestion des clients permet de centraliser toutes les informations relatives aux clients de NOVALINK. Il offre une interface complète pour créer, modifier, consulter et supprimer des clients.

## 🎯 Fonctionnalités

### 1. Liste des Clients (`/clients`)
- **Affichage** : Tableau avec colonnes : Client, Contact, Localisation, Sites, Incidents, Statut
- **Recherche** : Par nom, email ou téléphone
- **Filtres** : Actifs / Inactifs / Tous
- **Actions** : Voir, Modifier, Supprimer (admin uniquement)
- **Design** : Avatar circulaire avec initiale, badges pour compteurs

### 2. Création de Client (`/clients/create`)
- **Champs obligatoires** :
  - Nom du client
- **Champs optionnels** :
  - Email
  - Téléphone
  - Adresse complète
  - Ville
  - Pays (Côte d'Ivoire par défaut)
  - Personne de contact
  - Téléphone de contact
  - Notes internes
  - Statut (Actif par défaut)
- **Validation** : HTML5 + Bootstrap validation
- **Layout** : 2 colonnes (8+4) avec carte d'aide

### 3. Détail Client (`/clients/show?id=X`)
- **Hero Section** : Nom, statut, avatar avec dégradé violet
- **KPI Cards** : 4 cartes (Incidents Total, Ouverts, Résolus, Sites)
- **Informations** : Email, téléphone, adresse, contact
- **Sites** : Liste des locations avec compteur incidents
- **Incidents récents** : 10 derniers incidents avec lien vers détail
- **Actions rapides** : Déclarer incident, Ajouter site, Modifier, Activer/Désactiver, Supprimer

### 4. Modification Client (`/clients/edit?id=X`)
- **Formulaire** : Identique à création avec valeurs pré-remplies
- **Métadonnées** : Date création, dernière modification
- **Validation** : Identique à création

### 5. Suppression Client (`/clients/delete`)
- **Protection** : Impossible si incidents associés
- **Cascade** : Supprime les locations du client
- **Modal** : Confirmation avec nom du client
- **Restriction** : Admin uniquement

### 6. Activation/Désactivation (`/clients/toggle`)
- **Fonction** : Bascule le statut actif/inactif
- **Impact** : Clients inactifs n'apparaissent pas dans les sélections
- **Rôles** : Admin et Agent

## 🗄️ Structure de la Base de Données

### Table `clients`

```sql
CREATE TABLE `clients` (
  `id` INT(11) NOT NULL AUTO_INCREMENT,
  `name` VARCHAR(255) NOT NULL,
  `email` VARCHAR(255) DEFAULT NULL,
  `phone` VARCHAR(50) DEFAULT NULL,
  `address` TEXT DEFAULT NULL,
  `city` VARCHAR(100) DEFAULT NULL,
  `country` VARCHAR(100) DEFAULT 'Côte d''Ivoire',
  `contact_person` VARCHAR(255) DEFAULT NULL,
  `contact_phone` VARCHAR(50) DEFAULT NULL,
  `notes` TEXT DEFAULT NULL,
  `active` TINYINT(1) NOT NULL DEFAULT 1,
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP NULL DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_name` (`name`),
  KEY `idx_active` (`active`),
  KEY `idx_email` (`email`),
  KEY `idx_city` (`city`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### Relations
- **locations** : `locations.client_id` → `clients.id` (ON DELETE RESTRICT)
- **incidents** : `incidents.client_id` → `clients.id` (ON DELETE RESTRICT)

## 🔐 Permissions

| Action | Admin | Manager | Superviseur | Agent | Technicien |
|--------|-------|---------|-------------|-------|------------|
| Voir liste | ✅ | ✅ | ✅ | ✅ | ✅ |
| Voir détail | ✅ | ✅ | ✅ | ✅ | ✅ |
| Créer | ✅ | ❌ | ❌ | ✅ | ❌ |
| Modifier | ✅ | ❌ | ❌ | ✅ | ❌ |
| Activer/Désactiver | ✅ | ❌ | ❌ | ✅ | ❌ |
| Supprimer | ✅ | ❌ | ❌ | ❌ | ❌ |

## 🎨 Design

### Palette de Couleurs
- **Hero** : Dégradé violet (#667eea → #764ba2)
- **Avatar** : Cercle bleu primaire avec initiale blanche
- **Badges** :
  - Actif : `bg-success` (vert)
  - Inactif : `bg-secondary` (gris)
  - Incidents : `bg-warning` (orange) si > 0, sinon `bg-secondary`
  - Sites : `bg-info` (bleu)

### Icônes (Font Awesome 6.5.2)
- Client : `fa-building`
- Email : `fa-envelope`
- Téléphone : `fa-phone`
- Mobile : `fa-mobile`
- Adresse : `fa-map-marker-alt`
- Contact : `fa-user-tie`
- Notes : `fa-sticky-note`

## 📁 Architecture des Fichiers

```
app/
├── Controllers/
│   └── ClientsController.php          # Contrôleur principal (CRUD + toggle)
└── Views/
    └── clients/
        ├── index.php                   # Liste des clients
        ├── create.php                  # Formulaire création
        ├── edit.php                    # Formulaire modification
        └── show.php                    # Détail client

database/
└── create_clients_table.sql            # Script création table + demo data

public/
└── index.php                           # Routes (lignes 103-110)
```

## 🛣️ Routes

```php
// Module Clients
$router->get('/clients', [ClientsController::class, 'index']);
$router->get('/clients/create', [ClientsController::class, 'create']);
$router->post('/clients/create', [ClientsController::class, 'store']);
$router->get('/clients/show', [ClientsController::class, 'show']);
$router->get('/clients/edit', [ClientsController::class, 'edit']);
$router->post('/clients/edit', [ClientsController::class, 'update']);
$router->post('/clients/delete', [ClientsController::class, 'delete']);
$router->post('/clients/toggle', [ClientsController::class, 'toggle']);
```

## 🚀 Installation

### 1. Exécuter le Script SQL
```bash
# Via MySQL CLI
mysql -u root -p bd_insuite_backbone < database/create_clients_table.sql

# Ou via phpMyAdmin : importer le fichier
```

### 2. Vérifier les Routes
Les routes sont déjà configurées dans `public/index.php` (lignes 103-110)

### 3. Vérifier le Menu
Le menu "Clients" est déjà ajouté dans `app/Views/layouts/main.php` (après Incidents)

### 4. Tester l'Accès
```
http://localhost/Insuite_backbones/public/clients
```

## 🧪 Tests

### Scénarios de Test

1. **Création basique**
   - Remplir uniquement le nom
   - Vérifier création réussie
   - Vérifier redirection vers liste avec message succès

2. **Création complète**
   - Remplir tous les champs
   - Vérifier sauvegarde correcte
   - Vérifier affichage dans détail

3. **Recherche**
   - Rechercher par nom partiel
   - Rechercher par email
   - Rechercher par téléphone
   - Vérifier résultats filtrés

4. **Filtres**
   - Filtrer clients actifs
   - Filtrer clients inactifs
   - Vérifier compteur

5. **Modification**
   - Modifier nom
   - Modifier statut
   - Vérifier mise à jour `updated_at`

6. **Suppression**
   - Tenter supprimer client avec incidents → Erreur
   - Supprimer client sans incidents → Succès
   - Vérifier cascade sur locations

7. **Intégration Incidents**
   - Créer incident pour client
   - Vérifier compteur dans liste
   - Vérifier affichage dans détail client

8. **Permissions**
   - Tester accès admin → OK
   - Tester accès agent → OK (création/modif)
   - Tester accès technicien → Liste/Détail OK, création KO

## 📊 Statistiques Disponibles

Dans la page détail client :
- **Total incidents** : Nombre total d'incidents du client
- **Incidents ouverts** : Status IN ('open', 'ouvert', 'nouveau')
- **Incidents résolus** : Status IN ('closed', 'clos', 'cloture')
- **Sites gérés** : Nombre de locations

## 🔄 Intégrations

### Avec Module Incidents
- Lien "Déclarer incident" pré-remplit `client_id`
- Liste incidents filtrée par client
- Compteur incidents dans liste/détail

### Avec Module Locations
- Lien "Ajouter site" pré-remplit `client_id`
- Liste sites avec compteur incidents
- Foreign key cascade

## 📝 Messages d'Erreur

| Code | Message | Cause |
|------|---------|-------|
| `name_required` | Le nom du client est obligatoire | Nom vide |
| `database` | Une erreur est survenue | Erreur SQL |
| `has_incidents` | Impossible de supprimer : X incident(s) associé(s) | Tentative suppression avec incidents |

## 📝 Messages de Succès

| Code | Message |
|------|---------|
| `created` | Client créé avec succès ! |
| `updated` | Client mis à jour avec succès ! |
| `deleted` | Client supprimé avec succès ! |
| `toggled` | Statut du client modifié avec succès ! |

## 🎯 Bonnes Pratiques

1. **Validation**
   - Toujours valider le nom (obligatoire)
   - Valider format email si fourni
   - Sanitizer les entrées utilisateur

2. **Sécurité**
   - Vérifier permissions avant actions sensibles
   - Protection CSRF implicite (session)
   - Échappement HTML dans vues

3. **UX**
   - Messages de feedback clairs
   - Redirections logiques après actions
   - Confirmation avant suppression

4. **Performance**
   - Indexes sur `name`, `email`, `city`, `active`
   - Requêtes avec LEFT JOIN pour stats
   - Pagination si > 100 clients (à implémenter si nécessaire)

## 🐛 Dépannage

### Erreur "Table 'clients' doesn't exist"
→ Exécuter `database/create_clients_table.sql`

### Erreur "Foreign key constraint fails"
→ Vérifier que tables `locations` et `incidents` existent

### Menu "Clients" n'apparaît pas
→ Vider cache navigateur, vérifier fichier `layouts/main.php`

### Page blanche sur `/clients`
→ Vérifier logs Apache/PHP, vérifier namespace `ClientsController`

## 🔮 Évolutions Futures

- [ ] Export CSV/Excel de la liste clients
- [ ] Import en masse via CSV
- [ ] Historique des modifications
- [ ] Documents attachés (contrats, devis)
- [ ] Gestion multi-contacts
- [ ] Facturation intégrée
- [ ] Pagination de la liste (si > 100)
- [ ] Tri personnalisable des colonnes
- [ ] Dashboard client (métriques SLA, satisfaction)

## 📞 Support

Pour toute question sur le module clients :
1. Consulter cette documentation
2. Vérifier les logs : `storage/logs/`
3. Contacter l'équipe de développement

---

**Date de création** : 15 décembre 2025  
**Version** : 1.0.0  
**Auteur** : GitHub Copilot  
**Projet** : NOVALINK - Insuite Backbones