================================
Tenant — Schema Manager
================================

Le Schema Manager orchestre le cycle de vie complet des schémas PostgreSQL
pour les tenants (création, migration, clonage, backup, restauration).

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

.. module:: src.module.tenant.infrastructure.schema_manager
   :synopsis: Gestion du cycle de vie des schémas tenant


Fonctions principales
======================

.. function:: create_schema(tenant) -> None

   Crée le schéma PostgreSQL pour un tenant et exécute les migrations initiales.

   Délègue au backend d'isolation configuré.

.. function:: clone_schema(source_tenant, target_slug: str) -> None

   Clone le schéma d'un tenant source vers un nouveau tenant.
   Copie les tables **et** les données.

   Utile pour créer des environnements de test ou des sandbox.

   .. code-block:: python

      from src.module.tenant.infrastructure.schema_manager import clone_schema

      clone_schema(production_tenant, "staging-acme")

.. function:: drop_schema(tenant, *, backup: bool = False) -> None

   Supprime le schéma d'un tenant.

   :param tenant: Tenant à supprimer
   :param backup: Si ``True``, effectue un backup avant la suppression

   .. warning::

      **DESTRUCTIF.** Toutes les données du tenant sont perdues.

.. function:: migrate_schema(tenant) -> None

   Applique les migrations Django au schéma d'un tenant spécifique.

.. function:: migrate_all_schemas() -> dict[str, bool]

   Migre tous les schémas tenant en batch.

   :returns: Dictionnaire ``{schema_name: success}`` pour chaque tenant.

   .. code-block:: python

      from src.module.tenant.infrastructure.schema_manager import migrate_all_schemas

      results = migrate_all_schemas()
      failed = {k: v for k, v in results.items() if not v}
      if failed:
          print(f"Échec de migration pour : {list(failed.keys())}")


Introspection
=============

.. function:: schema_exists(schema_name: str) -> bool

   Vérifie si un schéma PostgreSQL existe.

.. function:: list_schemas(prefix: str | None = None) -> list[str]

   Liste tous les schémas tenant.

   :param prefix: Préfixe de filtrage (défaut: ``TENANT_SCHEMA_PREFIX``)

.. function:: check_schema_drift() -> dict[str, list[str]]

   Détecte les incohérences de migration entre les schémas tenant.
   Compare les migrations appliquées dans chaque schéma.

   :returns: Dictionnaire ``{schema_name: [missing_migrations]}``


Backup et Restauration
======================

.. function:: backup_schema(tenant, output_dir: str = ".") -> str

   Exécute un ``pg_dump`` du schéma tenant.

   :param tenant: Tenant à sauvegarder
   :param output_dir: Répertoire de sortie
   :returns: Chemin du fichier dump

.. function:: restore_schema(tenant, dump_file: str) -> None

   Restaure un schéma tenant depuis un dump ``pg_dump``.

   :param tenant: Tenant cible
   :param dump_file: Chemin du fichier dump


Database Router
===============

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

.. module:: src.module.tenant.infrastructure.db_router
   :synopsis: Routeur de base de données tenant-aware

.. class:: TenantAwareDatabaseRouter

   Routeur qui contrôle les migrations pour le mode schema.

   .. method:: db_for_read(model, **hints) -> str

      Route les lectures vers la base ``default``.

   .. method:: db_for_write(model, **hints) -> str

      Route les écritures vers la base ``default``.

   .. method:: allow_relation(obj1, obj2, **hints) -> bool

      Autorise toutes les relations.

   .. method:: allow_migrate(db, app_label, model_name=None, **hints) -> bool

      Contrôle quels modèles sont migrés dans quel schéma.

      Pendant une migration tenant (flag ``_migrating_tenant_schema``),
      seuls les modèles ``TenantSpecificModel`` sont autorisés.
      Sinon, seuls les modèles partagés sont migrés.