# Invitations & mots de passe (Mailjet)

Ce document decrit l'envoi d'e-mails via **Mailjet** et le fonctionnement des
**invitations** et **reinitialisations** de mot de passe des comptes de
l'administration.

## 1. Principe

- **Invitation** : a la creation d'un utilisateur dans l'admin, l'administrateur
  peut choisir d'**envoyer une invitation par e-mail** (comportement par
  defaut). La personne recoit un lien et **definit elle-meme son mot de passe**.
  Le compte existe mais reste « en attente » (badge dans la liste) tant qu'elle
  n'a pas clique.
  - Alternative : l'administrateur peut desactiver l'invitation et **saisir un
    mot de passe manuellement** (depannage).
- **Reinitialisation** : elle ne peut etre declenchee **que par un
  administrateur**, depuis la fiche ou la liste des utilisateurs (action
  « Reinitialiser le mot de passe »). **Il n'existe volontairement aucun
  « mot de passe oublie » self-service** sur la page de connexion.
- Les liens (invitation et reinitialisation) s'appuient sur le mecanisme de
  jetons de Laravel (`password_reset_tokens`), a **usage unique** et
  **valables 7 jours** (configurable, voir plus bas).

## 2. Configuration Mailjet (production)

> ⚠️ **Le mutualise OVH bloque le SMTP sortant** (constate en prod : port 587
> « connection closed », port 465 « connection refused »). On n'utilise donc
> **PAS** le SMTP mais l'**API HTTP de Mailjet** (HTTPS, port 443), qui n'est pas
> bloquee. Le transport est maison
> (`App\Mail\Transport\MailjetApiTransport`, enregistre dans
> `AppServiceProvider`) et s'appuie sur le client HTTP de Laravel : **aucun
> paquet Composer a installer**.

Dans le `.env` de production (jamais commite ; secrets fournis par le client
via l'interface Mailjet) :

```dotenv
MAIL_MAILER=mailjet
MAILJET_APIKEY=<CLE_API_MAILJET>        # "API Key" (cle publique) Mailjet
MAILJET_APISECRET=<CLE_SECRETE_MAILJET> # "Secret Key" (cle privee) Mailjet
MAIL_FROM_ADDRESS="no-reply@biome.immo" # adresse expeditrice validee chez Mailjet
MAIL_FROM_NAME="Biome Constructions"
```

> Les cles Mailjet se trouvent dans Mailjet > **Account settings > API Key
> Management** (API Key = `MAILJET_APIKEY`, Secret Key = `MAILJET_APISECRET`).

Test rapide de l'envoi (apres `php artisan optimize:clear`, sans `config:cache`) :

```bash
php artisan tinker --execute="Mail::raw('Test API Mailjet', fn(\$m)=>\$m->to('vous@exemple.com')->subject('Test Biome'));"
```

Aucune exception = e-mail parti (verifier la reception + Mailjet > Statistiques).

### Adresse expeditrice

L'adresse `MAIL_FROM_ADDRESS` doit etre **validee** dans Mailjet
(*Senders & Domains*), idealement avec **SPF/DKIM** configures sur le domaine,
sinon les e-mails partent en spam ou sont refuses.

### Duree de validite des liens

Par defaut **7 jours** (10080 minutes). Reglable via `config/auth.php`
(`passwords.users.expire`) ou l'env :

```dotenv
AUTH_PASSWORD_RESET_EXPIRE=10080
```

## 3. En local / recette

Le `.env.example` laisse `MAIL_MAILER=log` : les e-mails ne sont pas envoyes
mais **ecrits dans `storage/logs/laravel.log`** (pratique pour recuperer le
lien sans configurer Mailjet). En tests automatises, le driver `array` est
utilise (aucun envoi).

## 4. Fonctionnement interne (pour un developpeur)

- **`App\Services\Comptes\InvitationsUtilisateur`** : genere le jeton
  (`Password::broker()->createToken()`) et envoie le mail
  (`App\Mail\LienMotDePasseMail`, variante invitation/reinitialisation).
- **Creation** : `App\Filament\Resources\Users\Pages\CreateUser` cree le compte
  (mot de passe aleatoire inutilisable si invitation, `mot_de_passe_defini_le`
  nul) puis envoie l'invitation.
- **Reinitialisation** :
  `App\Filament\Resources\Users\Actions\ReinitialiserMotDePasseAction`
  (reservee a la permission `utilisateurs.manage`), presente en action de ligne
  et d'en-tete de la ressource Utilisateurs.
- **Definition du mot de passe** :
  `App\Http\Controllers\Admin\DefinitionMotDePasseController` +
  vue `resources/views/admin/definir-mot-de-passe.blade.php`, routes
  `mot-de-passe.definir` (GET) / `mot-de-passe.enregistrer` (POST). Le jeton est
  valide via `Password::broker()->reset()` ; a la reussite, la personne est
  connectee et redirigee vers `/admin`.
- **Statut** : colonne `users.mot_de_passe_defini_le` (nulle = invitation en
  attente). Les comptes anterieurs sont marques actifs par la migration.

## 5. Deploiement

`git pull` + `php artisan migrate --force` (nouvelle colonne
`mot_de_passe_defini_le`) + `php artisan optimize:clear`. Renseigner les
variables Mailjet dans le `.env` de prod. Aucun `config:cache` (interdit sur
l'OVH mutualise, voir `docs/deploiement-preproduction.md`).