feat(commercial) : SupplierProvider + SupplierProcessor + gating compta (ERP-87) (#66)

## ERP-87 — Provider + Processor du répertoire fournisseurs (M2) Étape 3/7 du pipeline M2. Dépend de #86, bloque #88/#91/#92. Jumelle du M1 (Client*). ### Livré - **SupplierProvider** : liste paginée (Paginator ORM), exclusion archivés + soft-deletes par défaut, filtres `includeArchived`/`categoryCode`/`siteId`/`search`, échappatoire `?pagination=false`, item 404 si soft-delete (RG-2.17). - **SupplierProcessor** : normalisation `companyName`, archivage `isArchived`/`archivedAt` (RG-2.14/2.15), gating fin accounting/manage en **mode strict** (403 sur tout payload hors-permission, RG-2.16), 409 doublon `companyName` + conflit de restauration (RG-2.11). - **SupplierReadGroupContextBuilder** : ajoute `supplier:read:accounting` au contexte de lecture si `accounting.view` → gating compta + RIB **par omission de clé** (parade bug #4 M1). Un Provider ne pouvant pas influencer les groupes de sérialisation, c'est le point d'extension idiomatique (miroir de `ClientReadGroupContextBuilder`). - **SupplierFieldNormalizer** : normalisation serveur (RG-2.12). - **Supplier** : ajout `#[ApiResource]` (GetCollection/Get/Post/Patch) wirant Provider/Processor. ### Décision d'archi La spec décrit « le Provider retire le groupe accounting » — techniquement impossible (le Provider ne touche pas les groupes de sérialisation). Implémenté via décorateur `SerializerContextBuilder` (mirror M1), résultat fonctionnel identique (clé absente sans permission). ### Hors périmètre (ticket suivant #5) Validators métier : RG-2.03 (complétude Information Commerciale), RG-2.07 (Virement→banque), RG-2.08 (LCR→RIB), RG-2.10 (catégorie type FOURNISSEUR). Le Processor est structuré pour les accueillir. ### À noter Les permissions `commercial.suppliers.*` (référencées par les `security`) ne sont pas encore déclarées — ticket RBAC #7. Sans elles, `is_granted` renvoie `false` (pas d'erreur de compilation). ### Vérifs - `make test` : 483/483 vert - `make php-cs-fixer-allow-risky` : appliqué --------- Co-authored-by: Matthieu <contact@malio.fr> Reviewed-on: #66 Co-authored-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr> Co-committed-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
2026-06-08 07:29:51 +00:00
parent 3e138e1c17
commit e77c6378d3
5 changed files with 908 additions and 5 deletions
@@ -0,0 +1,191 @@
+<?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\Supplier;
+use App\Module\Commercial\Domain\Repository\SupplierRepositoryInterface;
+use Doctrine\ORM\Tools\Pagination\Paginator as DoctrinePaginator;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+
+/**
+ * Provider du repertoire fournisseurs (M2). Cf. spec-back M2 § 4.1 / § 4.2 +
+ * RG-2.17. Jumeau du ClientProvider (M1).
+ *
+ * Collection (GET /api/suppliers) :
+ *  - exclut par defaut les archives (is_archived = true) ET les soft-deletes
+ *    (deleted_at IS NOT NULL) — RG-2.17 ;
+ *  - ?includeArchived=true reintegre les archives (les soft-deletes restent
+ *    exclus au M2) — RG-2.17 ;
+ *  - tri par defaut companyName ASC — RG-2.17 ;
+ *  - filtres ?search=... (fuzzy companyName + contacts lies : firstName /
+ *    lastName / email — D1 refonte-contact), ?categoryCode=<code> (fournisseurs
+ *    ayant >= 1 categorie de ce code, repetable) et ?siteId=<id> (fournisseurs
+ *    ayant >= 1 adresse rattachee a ce site, repetable) ;
+ *  - pagination obligatoire (regle ABSOLUE n°13) : Paginator ORM ; echappatoire
+ *    ?pagination=false pour alimenter un <select> sans pagination.
+ *
+ * Item (GET /api/suppliers/{id} + provider de PATCH) :
+ *  - 404 si introuvable OU soft-delete (deleted_at non null, jamais expose au
+ *    M2) ; les archives restent consultables/restaurables en detail.
+ *
+ * Le filtrage des champs comptables en lecture (groupe supplier:read:accounting)
+ * n'est PAS fait ici mais dans SupplierReadGroupContextBuilder : un Provider
+ * retourne des donnees mais ne peut pas influencer les groupes de serialisation.
+ * Le contexte de normalisation est construit par le SerializerContextBuilder, en
+ * amont du serializer — c'est le point d'extension idiomatique d'API Platform
+ * pour conditionner le groupe accounting selon la permission de l'utilisateur.
+ *
+ * @implements ProviderInterface<Supplier>
+ */
+final class SupplierProvider implements ProviderInterface
+{
+    public function __construct(
+        #[Autowire(service: 'App\Module\Commercial\Infrastructure\Doctrine\DoctrineSupplierRepository')]
+        private readonly SupplierRepositoryInterface $repository,
+        private readonly Pagination $pagination,
+    ) {}
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): iterable|Paginator|Supplier|null
+    {
+        if ($operation instanceof CollectionOperationInterface) {
+            return $this->provideCollection($operation, $context);
+        }
+
+        return $this->provideItem($uriVariables);
+    }
+
+    /**
+     * @param array<string, mixed> $context
+     *
+     * @return list<Supplier>|Paginator<Supplier>
+     */
+    private function provideCollection(Operation $operation, array $context): array|Paginator
+    {
+        $filters         = $context['filters'] ?? [];
+        $includeArchived = $this->readBool($filters['includeArchived'] ?? false);
+        $archivedOnly    = $this->readBool($filters['archivedOnly'] ?? false);
+        $search          = $filters['search'] ?? null;
+        // categoryCode accepte un code unique (?categoryCode=NEGOCIANT, selects)
+        // OU une liste (?categoryCode[]=A&categoryCode[]=B, drawer multi).
+        $categoryCodes = $this->readStringList($filters['categoryCode'] ?? []);
+        $siteIds       = $this->readIntList($filters['siteId'] ?? []);
+
+        // Filtrage delegue au repository (logique partagee avec l'export XLSX).
+        $qb = $this->repository->createListQueryBuilder(
+            $includeArchived,
+            is_string($search) ? $search : null,
+            $categoryCodes,
+            $siteIds,
+            $archivedOnly,
+        );
+
+        // Echappatoire ?pagination=false : collection complete sans Paginator
+        // (regle n°13 — utile pour un <select> cote front).
+        if (!$this->pagination->isEnabled($operation, $context)) {
+            /** @var list<Supplier> $suppliers */
+            $suppliers = $qb->getQuery()->getResult();
+            // Hydratation batchee des collections affichees (§ 2.12) : evite le
+            // N+1 si la serialisation touche categories/sites, sans cartesien.
+            $this->repository->hydrateListCollections($suppliers);
+
+            return $suppliers;
+        }
+
+        $limit  = $this->pagination->getLimit($operation, $context);
+        $page   = max(1, $this->pagination->getPage($context));
+        $offset = ($page - 1) * $limit;
+
+        $qb->setFirstResult($offset)->setMaxResults($limit);
+
+        // Le QB de selection ne porte pas de fetch-join to-many (§ 2.12) : le
+        // COUNT est simple, fetchJoinCollection inutile. On materialise la page
+        // puis on hydrate ses collections en lot (memes entites managees).
+        $paginator = new Paginator(new DoctrinePaginator($qb->getQuery(), fetchJoinCollection: false));
+        $this->repository->hydrateListCollections(iterator_to_array($paginator));
+
+        return $paginator;
+    }
+
+    /**
+     * @param array<string, mixed> $uriVariables
+     */
+    private function provideItem(array $uriVariables): ?Supplier
+    {
+        $id = $uriVariables['id'] ?? null;
+        if (!is_int($id) && !(is_string($id) && ctype_digit($id))) {
+            return null;
+        }
+
+        $supplier = $this->repository->findById((int) $id);
+        if (null === $supplier) {
+            return null;
+        }
+
+        // Soft-delete : jamais expose au M2 (HP-M3-1) — 404 via retour null.
+        // Les archives restent visibles en detail (consultation + restauration).
+        if (null !== $supplier->getDeletedAt()) {
+            return null;
+        }
+
+        return $supplier;
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * Normalise un filtre en liste de chaines. Tolere un code unique (string)
+     * ou une liste (?key[]=a&key[]=b). Trim + retrait des vides.
+     *
+     * @return list<string>
+     */
+    private function readStringList(mixed $raw): array
+    {
+        $values = is_array($raw) ? $raw : [$raw];
+
+        $out = [];
+        foreach ($values as $value) {
+            if (is_string($value) && '' !== trim($value)) {
+                $out[] = trim($value);
+            }
+        }
+
+        return $out;
+    }
+
+    /**
+     * Normalise un filtre en liste d'identifiants entiers positifs. Tolere une
+     * valeur unique ou une liste (?key[]=1&key[]=2).
+     *
+     * @return list<int>
+     */
+    private function readIntList(mixed $raw): array
+    {
+        $values = is_array($raw) ? $raw : [$raw];
+
+        $out = [];
+        foreach ($values as $value) {
+            if ((is_int($value) || (is_string($value) && ctype_digit($value))) && (int) $value > 0) {
+                $out[] = (int) $value;
+            }
+        }
+
+        return $out;
+    }
+}