Starseed/src/Module/Commercial/Domain/Repository/ClientRepositoryInterface.php

<?php

declare(strict_types=1);

namespace App\Module\Commercial\Domain\Repository;

use App\Module\Commercial\Domain\Entity\Client;
use Doctrine\ORM\QueryBuilder;

interface ClientRepositoryInterface
{
    public function findById(int $id): ?Client;

    public function save(Client $client): void;

    /**
     * Construit un QueryBuilder de liste pour le repertoire clients.
     * - Exclut toujours les clients soft-deletes (deleted_at IS NOT NULL, RG-1.24).
     * - Exclut les archives sauf si $includeArchived = true (RG-1.25).
     * - Tri par defaut : companyName ASC (RG-1.26).
     * - $search : recherche fuzzy insensible a la casse sur companyName +
     *   lastName + email (metacaracteres LIKE echappes). Ignore si null/vide.
     * - $categoryType : restreint aux clients possedant au moins une categorie
     *   du type donne (code). Ignore si null/vide.
     *
     * Filtrage centralise ICI (et non dans les providers/controllers) pour que
     * la liste paginee (ClientProvider) et l'export (ClientExportController)
     * partagent strictement la meme logique de selection.
     */
    public function createListQueryBuilder(
        bool $includeArchived = false,
        ?string $search = null,
        ?string $categoryType = null,
    ): QueryBuilder;
}