# Proposition - Dashboard Administrateur pour les Inscriptions

## 📊 Vue d'ensemble

Dashboard permettant aux administrateurs de visualiser, filtrer, rechercher et gérer toutes les inscriptions du système avec des statistiques en temps réel.

---

## 🎯 Objectifs

1. **Visualisation** : Afficher toutes les inscriptions avec leurs statuts
2. **Filtrage** : Filtrer par événement, statut, date, formule, etc.
3. **Recherche** : Rechercher par nom, email, téléphone
4. **Statistiques** : Afficher des métriques clés (totaux, par statut, par événement)
5. **Actions** : Permettre certaines actions (changer statut, voir détails, exporter)

---

## 🏗️ Architecture Proposée

### 1. Backend (Laravel)

#### A. Controller : `AdminRegistrationController`

**Localisation** : `api/app/Http/Controllers/Admin/RegistrationController.php`

**Méthodes proposées** :

```php
class AdminRegistrationController extends Controller
{
    // Liste paginée avec filtres
    public function index(Request $request): JsonResponse
    
    // Détails d'une inscription
    public function show(Registration $registration): JsonResponse
    
    // Statistiques globales
    public function stats(Request $request): JsonResponse
    
    // Changer le statut d'une inscription
    public function updateStatus(Request $request, Registration $registration): JsonResponse
    
    // Exporter les inscriptions (CSV/Excel)
    public function export(Request $request): Response
}
```

#### B. Routes API

**Localisation** : `api/routes/api.php`

```php
// Routes admin pour inscriptions
Route::middleware(['auth:sanctum', 'role:admin'])->prefix('admin/registrations')->group(function () {
    Route::get('/', [Admin\RegistrationController::class, 'index']); // Liste avec filtres
    Route::get('/stats', [Admin\RegistrationController::class, 'stats']); // Statistiques
    Route::get('/{registration}', [Admin\RegistrationController::class, 'show']); // Détails
    Route::patch('/{registration}/status', [Admin\RegistrationController::class, 'updateStatus']); // Changer statut
    Route::get('/export/csv', [Admin\RegistrationController::class, 'export']); // Export CSV
});
```

#### C. Resource API : `AdminRegistrationResource`

**Localisation** : `api/app/Http/Resources/AdminRegistrationResource.php`

**Données incluses** :
- Toutes les données de `RegistrationResource` existant
- Informations utilisateur complètes (email_verified_at, rôles)
- Informations de vérification (si inscription publique)
- Historique des changements de statut (si table d'audit existe)
- Informations de paiement (payments liés)

#### D. Request Validation : `UpdateRegistrationStatusRequest`

**Localisation** : `api/app/Http/Requests/UpdateRegistrationStatusRequest.php`

**Validation** :
- `status` : requis, enum RegistrationStatus
- `notes` : optionnel, string (pour justifier le changement)

#### E. Service (optionnel) : `AdminRegistrationService`

**Localisation** : `api/app/Services/AdminRegistrationService.php`

**Méthodes** :
- `getFilteredRegistrations($filters)` : Logique de filtrage complexe
- `calculateStats($filters)` : Calcul des statistiques
- `updateStatus($registration, $newStatus, $notes)` : Changer statut avec audit

---

### 2. Frontend (React)

#### A. Structure des fichiers

```
frontend/src/
├── pages/
│   └── admin/
│       └── RegistrationsDashboard.tsx    # Page principale
├── components/
│   └── admin/
│       ├── registrations/
│       │   ├── RegistrationsTable.tsx    # Tableau des inscriptions
│       │   ├── RegistrationFilters.tsx   # Barre de filtres
│       │   ├── RegistrationStats.tsx     # Cartes statistiques
│       │   ├── RegistrationDetails.tsx   # Modal détails
│       │   └── StatusBadge.tsx           # Badge de statut
│       └── layout/
│           └── AdminLayout.tsx          # Layout admin (sidebar, header)
├── lib/
│   └── api/
│       ├── services/
│       │   └── adminRegistrations.ts     # Service API
│       └── hooks/
│           └── useAdminRegistrations.ts  # Hook React
└── routes/
    └── admin.tsx                         # Routes admin
```

#### B. Page principale : `RegistrationsDashboard.tsx`

**Fonctionnalités** :
- Layout avec sidebar navigation
- Section statistiques en haut (cartes)
- Barre de filtres/recherche
- Tableau paginé des inscriptions
- Actions rapides (voir détails, changer statut)

#### C. Composants

**RegistrationsTable** :
- Colonnes : ID, Nom, Email, Événement, Formule, Statut, Date création, Actions
- Tri par colonne
- Pagination
- Sélection multiple (optionnel)

**RegistrationFilters** :
- Filtre par événement (select)
- Filtre par statut (checkboxes)
- Filtre par date (date range)
- Filtre par formule (select)
- Recherche texte (nom, email, téléphone)
- Bouton "Réinitialiser"

**RegistrationStats** :
- Cartes avec métriques :
  - Total inscriptions
  - En attente (draft)
  - Soumises (submitted)
  - Payées (paid)
  - Par événement (graphique)

**RegistrationDetails** :
- Modal avec toutes les informations
- Onglets : Informations, Paiement, Historique
- Actions : Changer statut, Exporter PDF

---

## 🔍 Fonctionnalités Détaillées

### 1. Filtrage et Recherche

**Filtres proposés** :
- **Événement** : Dropdown avec tous les événements actifs
- **Statut** : Multi-select (draft, submitted, paid, etc.)
- **Date de création** : Date range picker
- **Date de soumission** : Date range picker
- **Formule** : Dropdown (A, B, C, D)
- **Type d'inscription** : Public / Authentifiée
- **Pays** : Dropdown
- **Leader Haggai** : Checkbox (is_haggai_leader)

**Recherche** :
- Recherche globale (nom, prénom, email, téléphone)
- Recherche avec debounce (300ms)

### 2. Statistiques

**Métriques proposées** :
- **Total inscriptions** : Nombre total
- **Par statut** : Répartition (draft, submitted, paid, etc.)
- **Par événement** : Graphique en barres
- **Par formule** : Graphique en camembert
- **Évolution temporelle** : Graphique linéaire (inscriptions par jour)
- **Inscriptions publiques vs authentifiées** : Comparaison
- **Taux de vérification email** : % d'inscriptions publiques vérifiées

### 3. Actions Administrateur

**Actions proposées** :
- ✅ **Voir détails** : Modal avec toutes les informations
- ✅ **Changer statut** : Dropdown avec validation
- ⚠️ **Rejeter** : Avec raison (notes)
- ⚠️ **Annuler** : Avec raison
- 📧 **Renvoyer email** : Si inscription publique non vérifiée
- 📄 **Exporter** : CSV/Excel avec filtres appliqués
- 🔍 **Voir utilisateur** : Lien vers profil utilisateur (si page existe)

**Contraintes** :
- Seuls les admins peuvent changer les statuts
- Logging de toutes les actions (qui, quand, quoi)
- Validation des transitions de statut (ex: draft → paid impossible)

### 4. Affichage des Données

**Colonnes du tableau** :
1. ID (avec lien vers détails)
2. Nom complet (first_name + last_name)
3. Email (avec badge si vérifié)
4. Téléphone
5. Événement (nom + année)
6. Formule (code + titre)
7. Statut (badge coloré)
8. Date création
9. Date soumission
10. Actions (menu dropdown)

**Badges de statut** :
- `draft` : Gris (En attente)
- `submitted` : Bleu (Soumise)
- `pending_payment` : Orange (Paiement en attente)
- `paid` : Vert (Payée)
- `rejected` : Rouge (Rejetée)
- `cancelled` : Gris foncé (Annulée)
- `refunded` : Jaune (Remboursée)

---

## 🔐 Sécurité et Permissions

### Backend

1. **Middleware** :
   ```php
   Route::middleware(['auth:sanctum', 'role:admin'])
   ```

2. **Policy** : Créer `AdminRegistrationPolicy`
   - `viewAny` : Seulement admin
   - `view` : Admin peut voir toutes
   - `updateStatus` : Seulement admin

3. **Audit Trail** : Logger toutes les actions
   - Qui a changé le statut
   - Quand
   - Ancien statut → Nouveau statut
   - Notes/raison

### Frontend

1. **Protection de route** : Vérifier le rôle admin
2. **Masquer les actions** : Si pas admin, ne pas afficher les boutons
3. **Validation côté client** : Vérifier les permissions avant les appels API

---

## 📊 Exemple de Réponse API

### GET /api/admin/registrations?event_id=1&status=submitted&page=1

```json
{
  "data": [
    {
      "id": 1,
      "status": "submitted",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+22670123456",
      "country": "Burkina Faso",
      "event": {
        "id": 1,
        "name": "Sommet Haggai Francophone 2026",
        "slug": "sommet-haggai-franco-2026"
      },
      "pricing_plan": {
        "id": 1,
        "code": "A",
        "title": "Formule A - Sans hébergement"
      },
      "submitted_at": "2026-01-19T10:00:00Z",
      "user": {
        "id": 1,
        "email_verified_at": "2026-01-19T10:05:00Z",
        "roles": ["participant"]
      },
      "is_public_registration": true,
      "created_at": "2026-01-19T09:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "last_page": 8
  },
  "filters_applied": {
    "event_id": 1,
    "status": "submitted"
  }
}
```

### GET /api/admin/registrations/stats?event_id=1

```json
{
  "total": 150,
  "by_status": {
    "draft": 10,
    "submitted": 80,
    "pending_payment": 30,
    "paid": 25,
    "rejected": 3,
    "cancelled": 2
  },
  "by_event": {
    "sommet-haggai-franco-2026": 100,
    "seminaire-regional-hybride": 50
  },
  "by_plan": {
    "A": 40,
    "B": 35,
    "C": 20,
    "D": 5
  },
  "public_vs_authenticated": {
    "public": 120,
    "authenticated": 30
  },
  "verification_rate": 85.5,
  "timeline": [
    {"date": "2026-01-19", "count": 15},
    {"date": "2026-01-18", "count": 12}
  ]
}
```

---

## 🎨 Design UI/UX

### Style

- **Cohérence** : Utiliser la même charte graphique que le reste de l'app
- **Responsive** : Tableau scrollable horizontalement sur mobile
- **Accessibilité** : Contraste, navigation clavier, ARIA labels

### Composants Tailwind

- Utiliser les composants UI existants (`Button`, etc.)
- Créer de nouveaux composants réutilisables :
  - `DataTable` : Tableau générique avec pagination
  - `FilterBar` : Barre de filtres réutilisable
  - `StatsCard` : Carte de statistique
  - `StatusBadge` : Badge de statut coloré

---

## 📈 Phases d'Implémentation

### Phase 1 : Backend de base (MVP)
1. ✅ Créer `AdminRegistrationController` avec `index()` et `show()`
2. ✅ Créer `AdminRegistrationResource`
3. ✅ Ajouter routes avec middleware admin
4. ✅ Implémenter filtres de base (event_id, status)

### Phase 2 : Frontend de base (MVP)
1. ✅ Créer page `RegistrationsDashboard`
2. ✅ Créer composant `RegistrationsTable`
3. ✅ Créer composant `RegistrationFilters` (filtres de base)
4. ✅ Intégrer avec API

### Phase 3 : Statistiques
1. ✅ Backend : Endpoint `/stats`
2. ✅ Frontend : Composant `RegistrationStats`
3. ✅ Graphiques (Chart.js ou Recharts)

### Phase 4 : Actions avancées
1. ✅ Changer statut
2. ✅ Modal détails
3. ✅ Export CSV

### Phase 5 : Améliorations
1. ⚠️ Recherche avancée
2. ⚠️ Filtres additionnels
3. ⚠️ Audit trail complet
4. ⚠️ Notifications (si changement de statut)

---

## 🔄 Intégration avec l'Existant

### Réutilisation

1. **RegistrationResource** : Étendre pour admin (plus de données)
2. **RegistrationPolicy** : Ajouter méthodes admin
3. **ExportController** : Réutiliser la logique d'export
4. **Composants UI** : Réutiliser `Button`, etc.

### Compatibilité

- Ne pas casser les routes existantes
- Les routes admin sont séparées (`/admin/registrations`)
- Les utilisateurs non-admin ne voient pas ces routes

---

## 📝 Questions à Valider

1. **Permissions** : Seulement `admin` ou aussi `treasurer` ?
2. **Actions** : Quelles actions sont autorisées ? (changer statut, rejeter, etc.)
3. **Export** : Format préféré ? (CSV, Excel, PDF)
4. **Pagination** : Nombre d'éléments par page ? (20, 50, 100)
5. **Graphiques** : Bibliothèque préférée ? (Chart.js, Recharts, autre)
6. **Audit** : Besoin d'une table d'audit dédiée ou logs suffisent ?
7. **Notifications** : Notifier l'utilisateur si statut change ?

---

## ✅ Avantages de cette Approche

1. **Séparation claire** : Routes admin distinctes
2. **Réutilisable** : Composants frontend réutilisables
3. **Extensible** : Facile d'ajouter de nouvelles fonctionnalités
4. **Sécurisé** : Middleware et policies en place
5. **Performant** : Pagination, filtres côté serveur
6. **Maintenable** : Code organisé et documenté

---

## 🚀 Prochaines Étapes (après validation)

1. Valider cette proposition
2. Créer les todos détaillés
3. Commencer par Phase 1 (Backend MVP)
4. Tester avec des données réelles
5. Itérer selon les retours

---

**Document créé le** : 2026-01-XX  
**Auteur** : Assistant IA  
**Statut** : ⏳ En attente de validation