# Phase 1 Backend MVP - Dashboard Admin Inscriptions ✅

## 📋 Résumé

Phase 1 backend MVP complétée avec succès. Les routes admin pour lister et consulter les inscriptions sont opérationnelles.

---

## ✅ Fichiers Créés/Modifiés

### Migrations
1. ✅ `2026_01_19_111440_add_indexes_to_registrations_table_for_admin_dashboard.php`
   - Indexes sur `created_at`, `submitted_at`, `country` pour améliorer les performances

2. ✅ `2026_01_19_111449_create_registration_status_changes_table.php`
   - Table d'audit pour les changements de statut (préparée pour Phase 4)

### Models
3. ✅ `app/Models/RegistrationStatusChange.php`
   - Model avec relations vers `registration` et `actor` (user)

4. ✅ `app/Models/Registration.php` (modifié)
   - Ajout relation `statusChanges()`
   - Ajout scopes : `forEvent()`, `withStatus()`, `search()`, `createdBetween()`

### Policies
5. ✅ `app/Policies/RegistrationPolicy.php` (modifié)
   - Ajout méthodes admin :
     - `viewAnyAdmin()` : admin + treasurer
     - `viewAdmin()` : admin + treasurer
     - `updateStatus()` : admin seulement
     - `export()` : admin + treasurer

### Resources
6. ✅ `app/Http/Resources/AdminRegistrationResource.php`
   - Resource complet avec toutes les données + relations
   - Détection inscription publique
   - Historique des changements de statut

### Controllers
7. ✅ `app/Http/Controllers/Admin/RegistrationController.php`
   - `index()` : Liste paginée avec filtres
   - `show()` : Détails complets avec relations

### Routes
8. ✅ `routes/api.php` (modifié)
   - Routes ajoutées sous `/admin/registrations`
   - Middleware `auth:sanctum` (Policy enforcement dans controller)

---

## 🔌 Endpoints Disponibles

### GET /api/admin/registrations

**Description** : Liste paginée des inscriptions avec filtres

**Permissions** : Admin ou Treasurer (via Policy)

**Query Parameters** :
- `page` : Numéro de page (défaut: 1)
- `per_page` : Éléments par page (20, 50, 100 - défaut: 20)
- `event_id` : Filtrer par événement (integer)
- `status[]` : Filtrer par statut(s) (array ou string)
- `q` : Recherche textuelle (nom, email, téléphone)
- `created_from` : Date de début (ISO format)
- `created_to` : Date de fin (ISO format)

**Exemple** :
```
GET /api/admin/registrations?event_id=1&status[]=submitted&status[]=paid&q=john&per_page=50&page=1
```

**Réponse** :
```json
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 150,
    "last_page": 3,
    "from": 1,
    "to": 50
  },
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "filters_applied": {
    "event_id": "1",
    "status": ["submitted", "paid"],
    "q": "john",
    "created_from": null,
    "created_to": null
  }
}
```

### GET /api/admin/registrations/{id}

**Description** : Détails complets d'une inscription

**Permissions** : Admin ou Treasurer (via Policy)

**Réponse** :
```json
{
  "data": {
    "id": 1,
    "status": "submitted",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "event": {...},
    "pricing_plan": {...},
    "user": {
      "id": 1,
      "email_verified_at": "2026-01-19T10:05:00Z",
      "roles": ["participant"]
    },
    "payments": [...],
    "is_public_registration": true,
    "status_changes": [...]
  }
}
```

---

## 🔍 Filtres Implémentés

### Par événement
```php
?event_id=1
```

### Par statut (multi-select)
```php
?status[]=draft&status[]=submitted
// OU
?status=submitted
```

### Recherche textuelle
```php
?q=john
```
Recherche dans : `first_name`, `last_name`, `email`, `phone`, et concaténation `first_name + last_name`

### Par date de création
```php
?created_from=2026-01-01&created_to=2026-01-31
```

---

## 🔐 Sécurité

- ✅ **Middleware** : `auth:sanctum` sur toutes les routes
- ✅ **Policy** : Vérification via `$this->authorize()` dans controller
- ✅ **Pas de hardcoding** : Rôles vérifiés via Policy, pas de middleware `role:admin` en dur
- ✅ **Permissions différenciées** :
  - `admin` : Accès total (viewAnyAdmin, viewAdmin, updateStatus, export)
  - `treasurer` : Read-only + export (viewAnyAdmin, viewAdmin, export) **PAS** updateStatus

---

## ⚡ Performance

- ✅ **Eager Loading** : Toutes les relations chargées en une requête
  - `event`, `pricingPlan`, `user.roles`, `payments`
- ✅ **Indexes DB** : Ajoutés sur `created_at`, `submitted_at`, `country`
- ✅ **Pagination** : Server-side avec Laravel paginator
- ✅ **Scopes** : Filtrage optimisé via scopes Eloquent

---

## 📊 Structure des Données

### AdminRegistrationResource

Inclut :
- Toutes les données de base (héritées de RegistrationResource)
- Champs Séminaire (seminar_intent, recommended_*, etc.)
- Relations complètes (event, pricingPlan, user, payments, batch)
- Métadonnées admin :
  - `is_public_registration` : Détection automatique
  - `status_changes` : Historique des changements (si chargé)

---

## 🧪 Tests à Effectuer

### 1. Test d'accès (Policy)
```bash
# Avec token admin
curl -H "Authorization: Bearer {admin_token}" \
  http://localhost:8000/api/admin/registrations

# Avec token treasurer (devrait fonctionner)
curl -H "Authorization: Bearer {treasurer_token}" \
  http://localhost:8000/api/admin/registrations

# Sans token (devrait retourner 401)
curl http://localhost:8000/api/admin/registrations

# Avec token participant (devrait retourner 403)
curl -H "Authorization: Bearer {participant_token}" \
  http://localhost:8000/api/admin/registrations
```

### 2. Test de filtres
```bash
# Par événement
curl -H "Authorization: Bearer {admin_token}" \
  "http://localhost:8000/api/admin/registrations?event_id=1"

# Par statut
curl -H "Authorization: Bearer {admin_token}" \
  "http://localhost:8000/api/admin/registrations?status[]=submitted&status[]=paid"

# Recherche
curl -H "Authorization: Bearer {admin_token}" \
  "http://localhost:8000/api/admin/registrations?q=john"

# Date range
curl -H "Authorization: Bearer {admin_token}" \
  "http://localhost:8000/api/admin/registrations?created_from=2026-01-01&created_to=2026-01-31"
```

### 3. Test pagination
```bash
curl -H "Authorization: Bearer {admin_token}" \
  "http://localhost:8000/api/admin/registrations?per_page=50&page=2"
```

### 4. Test détails
```bash
curl -H "Authorization: Bearer {admin_token}" \
  http://localhost:8000/api/admin/registrations/1
```

---

## 🚀 Prochaines Étapes

### Phase 2 : Backend Audit (Préparation)
- ✅ Déjà fait (table + model créés)
- ⏳ Tester la relation `statusChanges()`

### Phase 3 : Backend Stats
- ⏳ Endpoint `/admin/registrations/stats`
- ⏳ Calculs agrégés (total, by_status, by_event, timeline)

### Phase 4 : Backend UpdateStatus
- ⏳ Classe `RegistrationStatusTransitions` (state machine)
- ⏳ Méthode `updateStatus()` avec validation
- ⏳ Insertion dans table d'audit

### Phase 5 : Backend Export
- ⏳ Méthode `export()` réutilisant `ExportController::participants()`

### Phase 6+ : Frontend
- ⏳ Dashboard React avec table + filtres
- ⏳ Statistiques + graphiques
- ⏳ Actions (changer statut, export)

---

## ⚠️ Notes Importantes

1. **Migration des indexes** : Si les indexes existent déjà, la migration peut échouer. Dans ce cas, commenter les lignes d'ajout d'index dans la migration ou les supprimer manuellement avant de migrer.

2. **Table d'audit** : Créée mais vide pour l'instant. Sera utilisée en Phase 4.

3. **Détection inscription publique** : Basée sur le rôle `guest` ou `email_verified_at === null`. Peut être ajustée si nécessaire.

4. **Scopes** : Les scopes sont réutilisables et peuvent être chaînés.

---

## 📝 Documentation API

Voir `PLAN_IMPLEMENTATION_DASHBOARD_ADMIN.md` pour la documentation complète de l'API.

---

**Statut** : ✅ Phase 1 Backend MVP **TERMINÉE**  
**Date** : 2026-01-19  
**Prêt pour** : Tests + Phase 3 (Stats)