<?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;

    /**
     * Codes des types de categorie rattaches (CategoryType::code), tableau vide
     * si aucun. Depuis le passage en ManyToMany, une categorie peut porter
     * plusieurs types : un module tiers teste l'appartenance via
     * `in_array($code, $category->getCategoryTypeCodes(), true)`. Pilote, cote
     * M2 Commercial, la RG-2.10 (une categorie de fournisseur doit etre de type
     * FOURNISSEUR).
     *
     * @return list<string>
     */
    public function getCategoryTypeCodes(): array;
}
