=====================================
SMTP par Tenant
=====================================

Chaque tenant peut configurer son propre serveur SMTP pour l'envoi
d'emails. Si aucune configuration n'est définie, le système utilise
les paramètres SMTP globaux de Django (définis dans ``.env``).


Modèle TenantSMTPConfig
=========================

Module : ``src.module.tenant.infrastructure.smtp``

.. class:: TenantSMTPConfig(SharedModel)

   Configuration SMTP par tenant, stockée dans le schéma public.

   .. attribute:: tenant
      :type: OneToOneField → Tenant

      Relation 1:1 avec le tenant.

   .. attribute:: host
      :type: CharField

      Hostname du serveur SMTP (ex: ``smtp.gmail.com``).

   .. attribute:: port
      :type: PositiveIntegerField

      Port SMTP (587 pour TLS, 465 pour SSL).

   .. attribute:: username
      :type: CharField

      Identifiant d'authentification SMTP.

   .. attribute:: password
      :type: CharField

      Mot de passe SMTP.

   .. attribute:: use_tls
      :type: BooleanField

      Utiliser STARTTLS (port 587).

   .. attribute:: use_ssl
      :type: BooleanField

      Utiliser SSL implicite (port 465).

   .. attribute:: from_email
      :type: EmailField

      Adresse expéditeur par défaut pour ce tenant.

   .. attribute:: timeout
      :type: PositiveIntegerField

      Timeout de connexion (secondes).

   .. attribute:: is_active
      :type: BooleanField

      Désactiver pour revenir aux paramètres SMTP globaux.

   :Table: ``mt_tenant_smtp_config``


Backend email tenant-aware
===========================

.. class:: TenantSMTPEmailBackend(SMTPBackend)

   Backend email Django qui utilise automatiquement la config SMTP du
   tenant courant (résolu via ``current_tenant_var``).

   Si le tenant n'a pas de ``TenantSMTPConfig`` active, le backend
   utilise les paramètres SMTP globaux de Django.

   .. code-block:: python

      # settings.py — pour rendre TOUS les emails tenant-aware :
      EMAIL_BACKEND = 'src.module.tenant.infrastructure.smtp.TenantSMTPEmailBackend'


Fonctions utilitaires
======================

.. function:: send_tenant_email(subject, body, to, from_email=None, html_body=None, ...) -> int

   Envoie un email via le serveur SMTP du tenant courant.

   .. code-block:: python

      from src.module.tenant.infrastructure.smtp import send_tenant_email

      send_tenant_email(
          subject="Facture prête",
          body="Votre facture est disponible.",
          to=["client@example.com"],
      )

.. function:: get_tenant_smtp_config() -> TenantSMTPConfig | None

   Retourne la config SMTP du tenant courant, ou ``None``.

.. function:: get_tenant_email_connection(config=None, fail_silently=False)

   Retourne une connexion SMTP configurée pour le tenant courant.

.. function:: get_tenant_from_email() -> str

   Retourne l'adresse expéditeur du tenant, ou le ``DEFAULT_FROM_EMAIL`` global.


Configuration via l'admin
==========================

Le modèle ``TenantSMTPConfig`` est enregistré dans l'admin Django avec
un formulaire structuré par sections :

- **Général** — tenant + activation
- **Serveur SMTP** — host, port, TLS/SSL, timeout
- **Authentification** — username, password
- **Expéditeur** — from_email

.. code-block:: python

   # Exemple de création via code
   from src.module.tenant.infrastructure.smtp import TenantSMTPConfig

   TenantSMTPConfig.objects.create(
       tenant=my_tenant,
       host="smtp.sendgrid.net",
       port=587,
       username="apikey",
       password="SG.xxxxx",
       use_tls=True,
       from_email="invoices@acme-corp.com",
   )


Flux de résolution
===================

.. code-block:: text

   send_mail() / send_tenant_email()
         │
         ▼
   get_current_tenant() ──► tenant_id
         │
         ▼
   TenantSMTPConfig.objects.get(tenant=..., is_active=True)
         │
         ├── trouvé ──► connexion SMTP tenant
         │
         └── non trouvé ──► connexion SMTP globale (settings.py / .env)