<?php

declare(strict_types=1);

namespace App\Shared\Domain\Contract;

/**
 * Interface minimale exposant ce qu'un module tiers (Commercial...) doit
 * connaitre d'une Category, sans creer de couplage direct vers le module
 * Catalog (regle ABSOLUE n°1 : pas d'import inter-modules).
 *
 * Implementee par App\Module\Catalog\Domain\Entity\Category.
 * Utilisee comme cible des ManyToMany Client.categories et
 * ClientAddress.categories via resolve_target_entities (cf. doctrine.yaml),
 * sur le meme modele que SiteInterface / UserInterface.
 */
interface CategoryInterface
{
    public function getId(): ?int;

    public function getName(): ?string;

    /**
     * Code technique stable de la categorie (Category::code), ou null si non
     * encore renseigne. Slug MAJUSCULE derive du nom a la creation, fige ensuite.
     * Expose pour permettre a un module tiers de filtrer/valider par categorie
     * metier sans dependre du libelle (`name`) ni de l'`id` (non deterministe
     * entre environnements) ni importer la classe concrete Category (regle
     * ABSOLUE n°1). Pilote, cote M1 Commercial :
     *  - RG-1.03 : un distributor doit referencer un client portant la categorie
     *    de code DISTRIBUTEUR (resp. COURTIER pour broker) ;
     *  - RG-1.29 : une adresse interdit les categories de code DISTRIBUTEUR /
     *    COURTIER (relations entre clients, pas des attributs d'adresse).
     */
    public function getCode(): ?string;

    /**
     * Code du type de categorie rattache (CategoryType::code), ou null si la
     * categorie n'a pas de type. Depuis ERP-78, le modele n'a plus qu'un seul
     * type (CLIENT) : le filtrage metier passe desormais par getCode() ci-dessus.
     * Conserve pour l'affichage / la retrocompatibilite.
     */
    public function getCategoryTypeCode(): ?string;
}
