<?php

declare(strict_types=1);

namespace App\Module\Transport\Domain\Repository;

use App\Module\Transport\Domain\Entity\Carrier;
use Doctrine\ORM\QueryBuilder;

/**
 * Contrat du repository transporteurs (M4). Implementation Doctrine :
 * App\Module\Transport\Infrastructure\Doctrine\DoctrineCarrierRepository.
 */
interface CarrierRepositoryInterface
{
    public function findById(int $id): ?Carrier;

    public function save(Carrier $carrier): void;

    /**
     * QueryBuilder de SELECTION (filtres + tri) pour la liste. Exclut les
     * soft-deletes (deleted_at IS NOT NULL) et, par defaut, les archives.
     * Fetch-join uniquement qualimatCarrier (ManyToOne, sur — § 2.11) : la liste
     * n'embarque aucune sous-collection. Tri par defaut name ASC.
     *
     * Perimetre d'archivage (aligne sur ClientProvider/SupplierProvider/
     * ProviderProvider — toggle « Voir les archives » d'ERP-173) :
     *   - $archivedOnly = true  -> uniquement les archives (is_archived = true) ;
     *   - sinon $includeArchived = true -> actifs + archives (echappatoire) ;
     *   - par defaut -> actifs seuls (is_archived = false).
     *   $archivedOnly a la priorite sur $includeArchived.
     *
     * @param list<string> $certificationTypes filtre repetable (OR) sur certificationType
     */
    public function createListQueryBuilder(
        bool $includeArchived = false,
        ?string $search = null,
        array $certificationTypes = [],
        bool $archivedOnly = false,
    ): QueryBuilder;
}
