Starseed/src/Module/Commercial/Infrastructure/ApiPlatform/State/Provider/ClientProvider.php

<?php

declare(strict_types=1);

namespace App\Module\Commercial\Infrastructure\ApiPlatform\State\Provider;

use ApiPlatform\Doctrine\Orm\Paginator;
use ApiPlatform\Metadata\CollectionOperationInterface;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\Pagination\Pagination;
use ApiPlatform\State\ProviderInterface;
use App\Module\Commercial\Domain\Entity\Client;
use App\Module\Commercial\Domain\Repository\ClientRepositoryInterface;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\QueryBuilder;
use Doctrine\ORM\Tools\Pagination\Paginator as DoctrinePaginator;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

/**
 * Provider du repertoire clients (M1). Cf. spec-back M1 § 4.1 / § 4.2.
 *
 * Collection (GET /api/clients) :
 *  - exclut par defaut les archives (is_archived = true) ET les soft-deletes
 *    (deleted_at IS NOT NULL) — RG-1.24 ;
 *  - ?includeArchived=true reintegre les archives (les soft-deletes restent
 *    exclus au M1) — RG-1.25 ;
 *  - tri par defaut companyName ASC — RG-1.26 ;
 *  - filtres ?search=... (fuzzy companyName + lastName + email) et
 *    ?categoryType=<code> (clients ayant >= 1 categorie de ce type) ;
 *  - pagination obligatoire (convention Starseed ERP-72) : Paginator ORM ;
 *    echappatoire ?pagination=false pour alimenter un <select> sans pagination.
 *
 * Item (GET /api/clients/{id} + provider de PATCH) :
 *  - 404 si introuvable OU soft-delete (deleted_at non null, jamais expose au
 *    M1) ; les archives restent consultables/restaurables en detail.
 *
 * Le filtrage des champs comptables en lecture (groupe client:read:accounting)
 * n'est PAS fait ici mais dans ClientReadGroupContextBuilder (le provider ne
 * peut pas influencer les groupes de serialisation).
 *
 * @implements ProviderInterface<Client>
 */
final class ClientProvider implements ProviderInterface
{
    public function __construct(
        #[Autowire(service: 'App\Module\Commercial\Infrastructure\Doctrine\DoctrineClientRepository')]
        private readonly ClientRepositoryInterface $repository,
        private readonly Pagination $pagination,
        private readonly EntityManagerInterface $em,
    ) {}

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): Client|iterable|Paginator|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->provideCollection($operation, $context);
        }

        return $this->provideItem($uriVariables);
    }

    /**
     * @param array<string, mixed> $context
     *
     * @return list<Client>|Paginator<Client>
     */
    private function provideCollection(Operation $operation, array $context): array|Paginator
    {
        $filters         = $context['filters'] ?? [];
        $includeArchived = $this->readBool($filters['includeArchived'] ?? false);

        $qb = $this->repository->createListQueryBuilder($includeArchived);
        $this->applySearch($qb, $filters['search'] ?? null);
        $this->applyCategoryType($qb, $filters['categoryType'] ?? null);

        // Echappatoire ?pagination=false : collection complete sans Paginator
        // (cf. convention ERP-72 — utile pour un <select> cote front).
        if (!$this->pagination->isEnabled($operation, $context)) {
            // @var list<Client> $result
            return $qb->getQuery()->getResult();
        }

        $limit  = $this->pagination->getLimit($operation, $context);
        $page   = max(1, $this->pagination->getPage($context));
        $offset = ($page - 1) * $limit;

        $qb->setFirstResult($offset)->setMaxResults($limit);

        // fetchJoinCollection: true pour un COUNT correct des que des JOINs
        // to-many seront ajoutes (sous-collections embarquees en detail).
        return new Paginator(new DoctrinePaginator($qb->getQuery(), fetchJoinCollection: true));
    }

    /**
     * @param array<string, mixed> $uriVariables
     */
    private function provideItem(array $uriVariables): ?Client
    {
        $id = $uriVariables['id'] ?? null;
        if (!is_int($id) && !(is_string($id) && ctype_digit($id))) {
            return null;
        }

        $client = $this->repository->findById((int) $id);
        if (null === $client) {
            return null;
        }

        // Soft-delete : jamais expose au M1 (HP-M2-1) — 404 via retour null.
        // Les archives restent visibles en detail (consultation + restauration).
        if (null !== $client->getDeletedAt()) {
            return null;
        }

        return $client;
    }

    /**
     * Recherche fuzzy insensible a la casse sur companyName + lastName + email.
     * Les metacaracteres LIKE (%, _, \) saisis sont echappes pour rester
     * litteraux.
     */
    private function applySearch(QueryBuilder $qb, mixed $search): void
    {
        if (!is_string($search) || '' === trim($search)) {
            return;
        }

        $escaped = str_replace(['\\', '%', '_'], ['\\\\', '\%', '\_'], trim($search));
        $pattern = '%'.mb_strtolower($escaped, 'UTF-8').'%';

        $qb->andWhere(
            'LOWER(c.companyName) LIKE :search '
            .'OR LOWER(c.lastName) LIKE :search '
            .'OR LOWER(c.email) LIKE :search',
        )->setParameter('search', $pattern);
    }

    /**
     * Restreint aux clients possedant au moins une categorie du type donne.
     * Sous-requete IN (plutot qu'un JOIN sur la collection M2M) pour ne pas
     * perturber le DISTINCT / ORDER BY de la requete paginee principale.
     */
    private function applyCategoryType(QueryBuilder $qb, mixed $categoryType): void
    {
        if (!is_string($categoryType) || '' === trim($categoryType)) {
            return;
        }

        // Sous-requete construite via l'EntityManager (et non
        // $repository->createQueryBuilder()) : createQueryBuilder() n'est pas
        // declaree sur ClientRepositoryInterface, l'appeler exposerait un detail
        // d'implementation Doctrine hors du contrat (fuite d'abstraction).
        $sub = $this->em->createQueryBuilder()
            ->select('c2.id')
            ->from(Client::class, 'c2')
            ->join('c2.categories', 'cat2')
            ->join('cat2.categoryType', 'ct2')
            ->where('ct2.code = :categoryType')
        ;

        $qb->andWhere($qb->expr()->in('c.id', $sub->getDQL()))
            ->setParameter('categoryType', trim($categoryType))
        ;
    }

    /**
     * Lit un flag booleen issu des query params. Accepte true / "true" / "1".
     */
    private function readBool(mixed $raw): bool
    {
        if (is_bool($raw)) {
            return $raw;
        }

        return is_string($raw) && in_array(strtolower($raw), ['true', '1'], true);
    }
}