# Intégration du Mail Hub Dasrwet dans l'Académie

> Tous les e-mails de l'académie sont envoyés via l'API centrale hébergée sur `audit.dasrwet.com`.
> Avantage : une seule config provider (SMTP/ACS/Graph) partagée, un seul log, une seule interface d'admin.

## Prérequis

**1. Générer un token API depuis l'admin audit.dasrwet.com**

- Se connecter sur `https://audit.dasrwet.com/admin`
- Menu **Mail Hub → Tokens API** → clic **Générer un nouveau token**
- Renseigner :
  - Nom : `plateforme-academie`
  - Scopes : `send:mail` (obligatoire)
  - Rate limit : 500/heure (largement suffisant)
- Copier le token affiché **UNE SEULE FOIS** dans la notification (format `aud_ac_...`)

**2. Configurer le `.env` de l'académie**

Ajouter (ou modifier) ces lignes dans `.env` :

```dotenv
MAIL_HUB_URL=https://audit.dasrwet.com
MAIL_HUB_TOKEN=aud_ac_XXXXXXXXXXXXXXXXXX
MAIL_HUB_FROM_ADDRESS=no-reply@geniac.fr
MAIL_HUB_FROM_NAME="GenIaC Académie"
MAIL_HUB_REPLY_TO=contact@geniac.fr
MAIL_HUB_ENABLED=true
```

## Usage dans le code

### Envois pré-câblés

**1. Bienvenue apprenant** — automatique à la création d'un `User`
- Fichier : `app/Observers/UserObserver.php`
- Template : `resources/views/emails/welcome_apprenant.blade.php`
- ✅ Aucune action requise, fonctionne dès activation

### Envois à câbler manuellement

Le helper `AcademieMailer` fournit des méthodes prêtes à l'emploi. Il suffit de les appeler dans les endroits pertinents de ton code :

**Confirmation de paiement** — dans le contrôleur de succès de checkout :

```php
use App\Services\AcademieMailer;

// Après validation du paiement (dans CheckoutController::success)
AcademieMailer::orderPaid($order);
```

**Rappel de session** — dans un scheduled task (Kernel.php) qui tourne quotidiennement :

```php
use App\Services\AcademieMailer;
use App\Models\Enrollment;

// Enrollments dont la session commence dans 7 jours
Enrollment::whereHas('session', fn ($q) =>
    $q->whereDate('date_debut', now()->addDays(7)->toDateString())
)->each(fn ($enrollment) =>
    AcademieMailer::sessionReminder($enrollment, daysBefore: 7)
);
```

**Attestation prête** — dans le service qui génère l'attestation :

```php
use App\Services\AcademieMailer;

// Après génération du PDF certificate
AcademieMailer::certificateReady($enrollment);
```

**Envoi générique** — pour tout cas ad-hoc (message formateur → apprenant, etc.) :

```php
use App\Services\AcademieMailer;

AcademieMailer::generic(
    to: 'apprenant@example.com',
    toName: 'Alice Dupont',
    subject: 'Info sur la session de demain',
    htmlContent: '<p>Bonjour Alice, la session de demain se tiendra en visio via ce lien : ...</p>',
    ctaUrl: 'https://zoom.us/j/1234567890',
    ctaLabel: 'Rejoindre la session',
);
```

## Où voir les envois

- Le log détaillé de tous les envois académie est visible sur : **https://audit.dasrwet.com/admin/mail-logs**
- Filtre par `Source = academie` pour voir uniquement ceux venant de l'académie
- Chaque ligne montre : destinataire, statut (envoyé/échec), erreur détaillée si problème

## Créer un nouveau template

**1. Créer la vue Blade** : `resources/views/emails/mon_nouveau_template.blade.php`

Le HTML sera automatiquement inséré dans le layout Dasrwet (header cyan + footer). Écris juste le contenu principal :

```blade
<h2 style="margin:0 0 16px; font-size:20px; color:#0b3a86;">Titre du mail</h2>

<p style="margin:0 0 12px; font-size:14px; line-height:1.6; color:#334155;">
    Bonjour {{ $toName ?? '' }},
</p>

{{-- Utilise les variables passées via `data` --}}
<p>{{ $customMessage }}</p>

{{-- CTA optionnel --}}
<div style="margin:28px 0; text-align:center;">
    <a href="{{ $ctaUrl }}" style="display:inline-block; background:#1ec4b4; color:#ffffff; padding:12px 28px; border-radius:8px; text-decoration:none; font-weight:600;">
        {{ $ctaLabel }}
    </a>
</div>
```

**2. L'appeler** depuis ton code :

```php
use App\Services\MailHubClient;

MailHubClient::send(
    to: 'user@example.com',
    toName: 'Alice',
    subject: 'Mon sujet',
    template: 'mon_nouveau_template',
    data: [
        'customMessage' => 'Message dynamique',
        'ctaUrl' => 'https://academie.geniac.fr/action',
        'ctaLabel' => 'Cliquer ici',
    ],
);
```

## Désactiver temporairement (dev / tests)

Dans `.env` :
```dotenv
MAIL_HUB_ENABLED=false
```

Les appels `MailHubClient::send()` retourneront `['ok' => false]` sans appel HTTP réel — utile en dev pour ne pas polluer le log de production.

## Dépannage

**Aucun mail n'arrive**
1. Vérifier `MAIL_HUB_TOKEN` renseigné dans `.env`
2. Vérifier `MAIL_HUB_ENABLED=true`
3. Vérifier le log académie : `storage/logs/laravel.log` (les erreurs MailHub y sont)
4. Vérifier `/admin/mail-logs` sur `audit.dasrwet.com` — la ligne apparaît-elle avec `source=academie` ?

**Erreur 401 Unauthorized**
- Le token est invalide ou révoqué. Régénérer depuis `/admin/mail-api-tokens`.

**Erreur 429 Too Many Requests**
- Rate limit horaire dépassé. Augmenter la limite du token dans l'admin audit.

**Erreur 422 Validation failed**
- Un champ obligatoire manque (`to.email`, `subject`, `template`). Voir le détail dans le log.

---

**Fin du guide — Mail Hub client v1 — 2026-08-20**