From 97301dcd6c3db0e880f88259d91490a171fe2587 Mon Sep 17 00:00:00 2001
From: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
Date: Wed, 3 Jun 2026 09:44:31 +0000
Subject: [PATCH] =?UTF-8?q?refactor(commercial)=20:=20d=C3=A9coupler=20l'h?=
 =?UTF-8?q?ydratation=20des=20collections=20de=20la=20s=C3=A9lection=20cli?=
 =?UTF-8?q?ents=20(ERP-100)=20(#50)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Contexte
Issu de la review ERP-62 (#44). `DoctrineClientRepository::createListQueryBuilder()` portait 3 `leftJoin+addSelect` to-many imbriqués (`categories × addresses × addresses.sites`) **partagés** entre :
- la **liste paginée** (`ClientProvider`) — bornée, OK ;
- l'**export XLSX** et **`?pagination=false`** — `getResult()` sans pagination → hydratation du **produit cartésien sur tout le référentiel** (1 client à 5 cat × 4 adr × 3 sites = 60 lignes SQL, × N clients).

Défaut d'altitude : un « QueryBuilder de liste » (contrat = filtres) imposait une stratégie d'hydratation à tout appelant.

## Changements
- **`createListQueryBuilder()`** redevient **filtres + tri seuls** — conforme au contrat de l'interface.
- Nouvelle méthode **`hydrateListCollections(array $clients)`** : recharge les collections en **2 requêtes `WHERE id IN(...)` séparées** (catégories d'un côté, adresses+sites de l'autre) via l'identity map Doctrine. Casse le triple cartésien en `cat + (addr × site)`.
- **3 appelants** branchés sur cette stratégie unique :
  - liste paginée : `fetchJoinCollection: false` (COUNT simple) + hydratation de la page ;
  - `?pagination=false` : hydratation après `getResult()` ;
  - export XLSX : hydratation après `getResult()`.

## Tests
- `make test` : **465 OK**.
- Nouveau test `ClientExportControllerTest::testExportPopulatesCategoryAndSiteColumns` : garde-fou sur les valeurs Catégories/Sites de l'export (qu'un oubli d'hydratation rendrait silencieusement vides).
- `php-cs-fixer` : 0 correction.

## Notes
- Benchmark « 1000+ clients » non exécuté (pas de jeu de données à cette échelle en dev) ; le cartésien est supprimé structurellement.
- `addr × site` reste un join imbriqué (inévitable pour agréger les sites par adresse), désormais non multiplié par les catégories.

Closes ERP-100.

---------

Co-authored-by: admin malio <malio@yuno.malio.fr>
Co-authored-by: Matthieu <contact@malio.fr>
Reviewed-on: https://gitea.malio.fr/MALIO-DEV/Starseed/pulls/50
Co-authored-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
Co-committed-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
---
 .../Repository/ClientRepositoryInterface.php  | 21 ++++++++
 .../State/Provider/ClientProvider.php         | 19 +++++--
 .../Controller/ClientExportController.php     |  5 ++
 .../Doctrine/DoctrineClientRepository.php     | 54 +++++++++++++++----
 .../Api/ClientExportControllerTest.php        | 35 ++++++++++++
 5 files changed, 120 insertions(+), 14 deletions(-)

diff --git a/src/Module/Commercial/Domain/Repository/ClientRepositoryInterface.php b/src/Module/Commercial/Domain/Repository/ClientRepositoryInterface.php
index 2bc081b..8bdafc7 100644
--- a/src/Module/Commercial/Domain/Repository/ClientRepositoryInterface.php
+++ b/src/Module/Commercial/Domain/Repository/ClientRepositoryInterface.php
@@ -33,6 +33,12 @@ interface ClientRepositoryInterface
      * la liste paginee (ClientProvider) et l'export (ClientExportController)
      * partagent strictement la meme logique de selection.
      *
+     * Contrat = SELECTION uniquement (filtres + tri). Aucun fetch-join to-many :
+     * l'hydratation des collections affichees est une decision de l'appelant
+     * (cf. {@see self::hydrateListCollections()}), pour ne pas imposer le cout
+     * d'un produit cartesien a un consommateur qui ne filtrerait/compterait que
+     * (ERP-100).
+     *
      * @param list<string> $categoryCodes
      * @param list<int>    $siteIds
      */
@@ -43,4 +49,19 @@ interface ClientRepositoryInterface
         array $siteIds = [],
         bool $archivedOnly = false,
     ): QueryBuilder;
+
+    /**
+     * Hydrate en lot les collections affichees par le repertoire (categories,
+     * adresses et leurs sites) sur un jeu de clients DEJA charges, via l'identity
+     * map Doctrine (memes instances). A appeler apres une selection bornee (page
+     * courante ou jeu d'export) pour eviter le N+1 a la serialisation, sans
+     * imposer de fetch-join au QueryBuilder de selection (ERP-100).
+     *
+     * Charge les categories et les adresses/sites en DEUX requetes distinctes
+     * (et non un triple fetch-join) pour ne pas multiplier categories x adresses
+     * x sites en un seul produit cartesien.
+     *
+     * @param list<Client> $clients
+     */
+    public function hydrateListCollections(array $clients): void;
 }
diff --git a/src/Module/Commercial/Infrastructure/ApiPlatform/State/Provider/ClientProvider.php b/src/Module/Commercial/Infrastructure/ApiPlatform/State/Provider/ClientProvider.php
index 7c47760..1d90cef 100644
--- a/src/Module/Commercial/Infrastructure/ApiPlatform/State/Provider/ClientProvider.php
+++ b/src/Module/Commercial/Infrastructure/ApiPlatform/State/Provider/ClientProvider.php
@@ -83,8 +83,13 @@ final class ClientProvider implements ProviderInterface
         // 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();
+            /** @var list<Client> $clients */
+            $clients = $qb->getQuery()->getResult();
+            // Hydratation batchee des collections affichees (cf. ERP-100) : evite
+            // le N+1 si la serialisation touche categories/sites, sans cartesien.
+            $this->repository->hydrateListCollections($clients);
+
+            return $clients;
         }
 
         $limit  = $this->pagination->getLimit($operation, $context);
@@ -93,9 +98,13 @@ final class ClientProvider implements ProviderInterface
 
         $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));
+        // Le QB de selection ne porte plus de fetch-join to-many (ERP-100) : 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;
     }
 
     /**
diff --git a/src/Module/Commercial/Infrastructure/Controller/ClientExportController.php b/src/Module/Commercial/Infrastructure/Controller/ClientExportController.php
index 44bd8f5..6bb0c50 100644
--- a/src/Module/Commercial/Infrastructure/Controller/ClientExportController.php
+++ b/src/Module/Commercial/Infrastructure/Controller/ClientExportController.php
@@ -69,6 +69,11 @@ final class ClientExportController
             ->getResult()
         ;
 
+        // Hydratation batchee des categories + adresses/sites (ERP-100) : le QB de
+        // selection ne fetch-join plus, on remplit les collections en 2 requetes
+        // IN bornees plutot que d'hydrater un produit cartesien sur tout le jeu.
+        $this->repository->hydrateListCollections($clients);
+
         $withSiren = $this->security->isGranted('commercial.clients.accounting.view');
 
         $binary = $this->exporter->export(
diff --git a/src/Module/Commercial/Infrastructure/Doctrine/DoctrineClientRepository.php b/src/Module/Commercial/Infrastructure/Doctrine/DoctrineClientRepository.php
index da60851..1457b21 100644
--- a/src/Module/Commercial/Infrastructure/Doctrine/DoctrineClientRepository.php
+++ b/src/Module/Commercial/Infrastructure/Doctrine/DoctrineClientRepository.php
@@ -38,16 +38,12 @@ class DoctrineClientRepository extends ServiceEntityRepository implements Client
         array $siteIds = [],
         bool $archivedOnly = false,
     ): QueryBuilder {
+        // SELECTION uniquement (filtres + tri) : pas de fetch-join to-many ici.
+        // L'hydratation des collections affichees (Catégories / Site(s)) est
+        // deleguee a hydrateListCollections() une fois le jeu borne, pour ne pas
+        // imposer un produit cartesien aux chemins non pagines (export,
+        // ?pagination=false) — ERP-100.
         $qb = $this->createQueryBuilder('c')
-            // Jointures + addSelect pour hydrater en une seule requete les
-            // collections affichees par le Repertoire (colonnes Catégories /
-            // Site(s)) : sans cela, la serialisation declenche un N+1 (une
-            // requete par client, puis par adresse). Le Paginator ORM
-            // (fetchJoinCollection: true, cf. ClientProvider) gere le COUNT
-            // malgre ces jointures to-many.
-            ->leftJoin('c.categories', 'cat')->addSelect('cat')
-            ->leftJoin('c.addresses', 'addr')->addSelect('addr')
-            ->leftJoin('addr.sites', 'site')->addSelect('site')
             ->andWhere('c.deletedAt IS NULL')
             ->orderBy('c.companyName', 'ASC')
         ;
@@ -66,6 +62,46 @@ class DoctrineClientRepository extends ServiceEntityRepository implements Client
         return $qb;
     }
 
+    public function hydrateListCollections(array $clients): void
+    {
+        if ([] === $clients) {
+            return;
+        }
+
+        // Ids des clients deja charges (entites managees). On rehydrate leurs
+        // collections via l'identity map : les requetes ci-dessous renvoient les
+        // MEMES instances Client, dont les collections sont alors remplies.
+        $ids = [];
+        foreach ($clients as $client) {
+            $id = $client->getId();
+            if (null !== $id) {
+                $ids[] = $id;
+            }
+        }
+        if ([] === $ids) {
+            return;
+        }
+
+        // 1re passe : categories (colonne « Catégories »). Produit c x cat seul.
+        $this->createQueryBuilder('c')
+            ->leftJoin('c.categories', 'cat')->addSelect('cat')
+            ->where('c.id IN (:ids)')->setParameter('ids', $ids)
+            ->getQuery()
+            ->getResult()
+        ;
+
+        // 2e passe : adresses + sites (colonne « Site(s) », sites portes par les
+        // adresses — RG-1.10). Le join addr -> site reste imbrique mais n'est
+        // plus multiplie par les categories : le cartesien global est casse.
+        $this->createQueryBuilder('c')
+            ->leftJoin('c.addresses', 'addr')->addSelect('addr')
+            ->leftJoin('addr.sites', 'site')->addSelect('site')
+            ->where('c.id IN (:ids)')->setParameter('ids', $ids)
+            ->getQuery()
+            ->getResult()
+        ;
+    }
+
     /**
      * Recherche fuzzy insensible a la casse sur companyName + lastName + email.
      * Les metacaracteres LIKE (%, _, \) saisis sont echappes pour rester
diff --git a/tests/Module/Commercial/Api/ClientExportControllerTest.php b/tests/Module/Commercial/Api/ClientExportControllerTest.php
index 80b1e06..ce04931 100644
--- a/tests/Module/Commercial/Api/ClientExportControllerTest.php
+++ b/tests/Module/Commercial/Api/ClientExportControllerTest.php
@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace App\Tests\Module\Commercial\Api;
 
+use App\Module\Commercial\Domain\Entity\ClientAddress;
+use App\Module\Sites\Domain\Entity\Site;
 use PhpOffice\PhpSpreadsheet\IOFactory;
 
 /**
@@ -88,6 +90,39 @@ final class ClientExportControllerTest extends AbstractCommercialApiTestCase
         self::assertNotContains('SECTEUR CO', $names);
     }
 
+    /**
+     * ERP-100 : depuis le decouplage hydratation/selection, le QueryBuilder de
+     * liste ne fetch-join plus les collections — l'export les recharge en lot via
+     * hydrateListCollections(). Ce test garde que les colonnes « Catégories » et
+     * « Site(s) » restent peuplees (un oubli d'hydratation les rendrait vides
+     * sans erreur).
+     */
+    public function testExportPopulatesCategoryAndSiteColumns(): void
+    {
+        $client = $this->createAdminClient();
+        $seed   = $this->seedClient('Hydrate Co', false, 'DISTRIBUTEUR');
+
+        $em   = $this->getEm();
+        $site = $em->getRepository(Site::class)->findOneBy([]);
+        self::assertNotNull($site, 'Aucun site seede : impossible de tester la colonne Site(s).');
+
+        $address = new ClientAddress();
+        $address->setClient($seed);
+        $address->setPostalCode('86100');
+        $address->setCity('Châtellerault');
+        $address->setStreet('1 rue du Test');
+        $address->addSite($site);
+        $em->persist($address);
+        $em->flush();
+
+        $flat = $this->flatten($this->gridFromResponse($client->request('GET', self::EXPORT_URL)->getContent()));
+
+        // Colonne « Catégories » : libelle de la categorie du client (getName()).
+        self::assertStringContainsString('test_cli_cat_distributeur', $flat);
+        // Colonne « Site(s) » : site agrege depuis l'adresse (RG-1.10).
+        self::assertStringContainsString((string) $site->getName(), $flat);
+    }
+
     public function testSirenColumnPresentWithAccountingView(): void
     {
         // L'admin bypass le RBAC : il a donc accounting.view -> colonne SIREN.