==========================
Stockage Tenant-Aware
==========================

Le module de stockage organise les fichiers téléchargés par tenant pour
prévenir l'accès cross-tenant aux fichiers.

Module : ``src.share_kernel.infrastructure.storage``

.. module:: src.share_kernel.infrastructure.storage
   :synopsis: Backends de stockage fichiers isolés par tenant


TenantFileSystemStorage
========================

.. class:: TenantFileSystemStorage(FileSystemStorage)

   Stockage sur le système de fichiers local, organisé par tenant.

   Structure : ``MEDIA_ROOT/tenants/<tenant_slug>/<upload_path>``

   .. method:: get_tenant_upload_root() -> str

      Retourne le répertoire racine pour le tenant courant.

   .. method:: path(name: str) -> str

      Retourne le chemin complet du fichier, scopé au tenant.

   .. method:: url(name: str) -> str

      Retourne l'URL du fichier, scopée au tenant.

   .. method:: save(name, content, max_length=None) -> str

      Sauvegarde un fichier sous le répertoire du tenant.
      Crée le répertoire automatiquement si nécessaire.

   **Configuration :**

   .. code-block:: python

      # settings.py
      DEFAULT_FILE_STORAGE = 'src.share_kernel.infrastructure.storage.TenantFileSystemStorage'

   **Structure sur disque :**

   .. code-block:: text

      media/
      ├── tenants/
      │   ├── acme-corp/
      │   │   ├── invoices/
      │   │   │   └── inv-001.pdf
      │   │   └── logos/
      │   │       └── logo.png
      │   └── beta-inc/
      │       └── invoices/
      │           └── inv-002.pdf
      └── shared/
          └── templates/
              └── default.pdf


TenantAzureBlobStorage
=======================

.. class:: TenantAzureBlobStorage(Storage)

   Backend Azure Blob Storage avec préfixes de blob scopés par tenant.

   Structure : ``<container>/tenants/<tenant_slug>/<name>``

   **Prérequis :** ``pip install azure-storage-blob``

   :param connection_string: Chaîne de connexion Azure (ou ``AZURE_STORAGE_CONNECTION_STRING``)
   :param container_name: Nom du container (ou ``AZURE_STORAGE_CONTAINER_NAME``, défaut: ``"media"``)
   :param custom_domain: Domaine CDN personnalisé (optionnel)
   :param overwrite_files: Autoriser l'écrasement (défaut: ``False``)

   .. method:: _open(name, mode="rb") -> File

      Ouvre et retourne un fichier depuis Azure Blob Storage.

   .. method:: _save(name, content) -> str

      Sauvegarde un fichier dans Azure Blob Storage.

   .. method:: delete(name) -> None

      Supprime un fichier d'Azure Blob Storage.

   .. method:: exists(name) -> bool

      Vérifie si un fichier existe.

   .. method:: size(name) -> int

      Retourne la taille du fichier en octets.

   .. method:: url(name) -> str

      Retourne l'URL du fichier (CDN si configuré).

   .. method:: listdir(path="") -> tuple[list[str], list[str]]

      Liste le contenu d'un répertoire (répertoires, fichiers).

   **Configuration :**

   .. code-block:: python

      # settings.py
      DEFAULT_FILE_STORAGE = 'src.share_kernel.infrastructure.storage.TenantAzureBlobStorage'

      AZURE_STORAGE_CONNECTION_STRING = "DefaultEndpointsProtocol=https;..."
      AZURE_STORAGE_CONTAINER_NAME = "media"
      AZURE_STORAGE_CUSTOM_DOMAIN = "cdn.example.com"  # Optionnel