<?php

declare(strict_types=1);

namespace App\Shared\Domain\Contract;

/**
 * Contrat opt-in pour les entites dont la visibilite est scopee par site.
 *
 * Une entite implementant cette interface sera :
 *  - filtree en lecture par SiteScopedQueryExtension (collection + item)
 *    selon le site courant de l'utilisateur authentifie ;
 *  - alimentee automatiquement en POST/PATCH par SiteAwareInjectionProcessor
 *    si le payload ne precise pas de site.
 *
 * L'implementation concrete doit :
 *  - Declarer une relation ManyToOne vers l'entite concrete Site avec colonne
 *    `site_id` NOT NULL (targetEntity: \App\Module\Sites\Domain\Entity\Site).
 *  - Indexer `site_id` en base (sinon le filtre WHERE genere un full-scan).
 *
 * Les signatures utilisent SiteInterface (et non la classe concrete Site)
 * pour que Shared n'importe pas directement le module Sites.
 *
 * Ne PAS implementer cette interface pour :
 *  - Des entites globales (catalogue partage, roles, permissions, users).
 *  - Des entites dont le scope est "par tenant" plus large que le site
 *    (utiliser TenantAwareInterface le cas echeant).
 *  - Des entites transversales references par plusieurs sites.
 *
 * Voir `docs/modules/site-aware.md` pour le guide d'adoption complet.
 */
interface SiteAwareInterface
{
    public function getSite(): ?SiteInterface;

    public function setSite(SiteInterface $site): void;
}
