[ERP-72] Paginer toutes les collections API + regle pagination obligatoire (#28)

## Contexte

Ticket Lesstime : [#72](https://lesstime.malio.fr/project/6/task/491) (id 491) — ticket transversal, pas de spec dediee : la description du ticket fait foi.

## Implementation

- **Defaut global de pagination** dans `config/packages/api_platform.yaml` : `items_per_page=10`, `maximum_items_per_page=50`, `client_items_per_page=true`, **`client_enabled=true`** (echappatoire `?pagination=false` pour alimenter les `<select>` cote front).
- **`CategoryProvider` refondu** : retourne maintenant un `ApiPlatform\Doctrine\Orm\Paginator(Doctrine\ORM\Tools\Pagination\Paginator(...))` au lieu d'un array brut. Supporte `?pagination=false`.
- **`AuditLogResource`** : override `paginationItemsPerPage=30 / max=50 / clientItemsPerPage=true` supprime, herite du global (10/50). `AuditLogProvider` (`DbalPaginator`) inchange.
- **Autres ressources** (`Category`, `CategoryType`, `User`, `Role`, `Permission`, `Site`) : aucun changement de code, heritent automatiquement.
- **Regle « pagination obligatoire »** documentee : `CLAUDE.md` (regle ABSOLUE n°13 + section « A NE PAS faire ») + `.claude/rules/backend.md` (nouvelle section dediee avec standard, override, selects, providers customs, garde-fou).
- **Garde-fou CI** : `tests/Architecture/CollectionsArePaginatedTest` echoue si une `GetCollection` desactive la pagination sans whitelist `EXCLUDED`.

## Adaptation collaterale (non prevue au plan initial)

7 appels `GET /api/<collection>` dans les tests existants (`CategoryListTest`, `PermissionApiTest`, `RoleApiTest`) ont recu `?pagination=false` parce qu'ils asseyaient sur le contenu complet de l'array. Sans cette adaptation, le commit Task 1 cassait `PermissionApiTest::testCollectionFilterByOrphanFalse`.

## Criteres d'acceptation

- [x] Toutes les collections API existantes paginees (plus aucun retour complet)
- [x] `itemsPerPage` par defaut (10) + max borne (50)
- [x] Tri / filtres / recherche fonctionnent combines a la pagination
- [x] `hydra:totalItems` (cle `totalItems` en JSON-LD API Platform 4) expose pour le front
- [x] Regle documentee (`CLAUDE.md` + `.claude/rules/backend.md`)

## Tests

- `docker exec -t php-starseed-fpm php -d memory_limit=512M vendor/bin/phpunit` → **Tests: 320, 0 failures** (etait 312 avant ce ticket → +8 nouveaux : 5 `CategoryPaginationTest` + 2 `AuditLogPaginationRegressionTest` + 1 `CollectionsArePaginatedTest`)
- `make php-cs-fixer-allow-risky` → 0 fix
- Verifications HTTP manuelles : voir cahier de test dans le ticket Lesstime #72

## Note d'incident

Le tout premier commit (`9060f5d`, pose du standard YAML) a ete cree avec `--no-verify` par un subagent qui n'a pas respecte la consigne explicite « jamais de bypass de hook ». La cause sous-jacente du hook failure etait un drift BDD locale sur `ColumnsHaveSqlCommentTest`, resolu ensuite via `make db-reset`. Les 6 commits suivants ont passe le hook normalement. Le contenu de `9060f5d` est correct (15 lignes YAML ajoutees) — a re-verifier en review.

## Reviewer suggere

A definir (Tristan etant l'auteur).

## Suite

Debloque le volet front **ERP-73** (pagination `MalioDataTable` + composable reutilisable + cablage `?pagination=false` sur les composables de select Role/Permission/Site/CategoryType).

Reviewed-on: #28
Co-authored-by: tristan <tristan@yuno.malio.fr>
Co-committed-by: tristan <tristan@yuno.malio.fr>

tests/Architecture/CollectionsArePaginatedTest.php

@@ -0,0 +1,126 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Architecture;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use Symfony\Component\Finder\Finder;
+
+/**
+ * Garde-fou architecture : toute operation `GetCollection` exposee via API Platform
+ * doit avoir la pagination activee (ou laisser la valeur par defaut, qui est
+ * activee globalement dans `config/packages/api_platform.yaml`).
+ *
+ * Interdit : `new GetCollection(paginationEnabled: false)` sans exception documentee.
+ *
+ * Raison : une collection non paginee peut retourner des milliers de lignes et
+ * saturer la memoire du serveur, le reseau et le navigateur. La pagination est la
+ * seule protection fiable contre ce risque sur un CRM a donnees croissantes.
+ *
+ * Quand ajouter une entree dans `EXCLUDED` :
+ * - La collection est structurellement bornee (referentiel statique, < 100 items,
+ *   jamais alimente par des utilisateurs) ET la suppression de la pagination est
+ *   documentee avec une justification metier explicite.
+ * - Format obligatoire : `FQCN => 'justification + reference ticket/spec'`
+ *
+ * @internal
+ */
+final class CollectionsArePaginatedTest extends TestCase
+{
+    /**
+     * Resources API Platform dont un `GetCollection` peut desactiver la pagination.
+     *
+     * Laisser vide au demarrage. Pour ajouter une exception :
+     *   'App\Module\Foo\Infrastructure\ApiPlatform\Resource\BarResource'
+     *       => 'Referentiel statique < 50 items (types de contrat). Cf. ERP-XX.',
+     *
+     * @var array<class-string, string>
+     */
+    private const EXCLUDED = [];
+
+    public function testAllGetCollectionOperationsHavePaginationEnabled(): void
+    {
+        $finder = new Finder()
+            ->files()
+            ->in(__DIR__.'/../../src')
+            ->name('*.php')
+            ->contains('#[ApiResource')
+        ;
+
+        // Garde : si le scan ne trouve rien, le chemin est casse — le test
+        // deviendrait un faux positif vert. On verifie qu'il a du grain a moudre.
+        self::assertNotEmpty(
+            iterator_to_array($finder),
+            'Aucun fichier #[ApiResource] trouve sous src/ : chemin invalide ou codebase vide.',
+        );
+
+        foreach ($finder as $file) {
+            $fqcn = $this->extractFqcn($file->getRealPath());
+            if (null === $fqcn || !class_exists($fqcn)) {
+                continue;
+            }
+
+            $reflection            = new ReflectionClass($fqcn);
+            $apiResourceAttributes = $reflection->getAttributes(ApiResource::class);
+
+            if ([] === $apiResourceAttributes) {
+                continue;
+            }
+
+            foreach ($apiResourceAttributes as $attribute) {
+                /** @var ApiResource $apiResource */
+                $apiResource = $attribute->newInstance();
+                $operations  = $apiResource->getOperations()?->getIterator() ?? [];
+
+                foreach ($operations as $operation) {
+                    if (!$operation instanceof GetCollection) {
+                        continue;
+                    }
+
+                    if (false !== $operation->getPaginationEnabled()) {
+                        continue;
+                    }
+
+                    // La pagination est explicitement desactivee : verifier
+                    // que la resource est dans la whitelist EXCLUDED.
+                    self::assertArrayHasKey(
+                        $fqcn,
+                        self::EXCLUDED,
+                        sprintf(
+                            "La resource %s desactive la pagination sur une operation GetCollection.\n"
+                            ."Regle : toute collection API Platform doit etre paginee (cf. .claude/rules/backend.md).\n"
+                            ."Si cette collection est structurellement bornee et que la desactivation est justifiee,\n"
+                            .'ajouter une entree dans CollectionsArePaginatedTest::EXCLUDED avec une justification.',
+                            $fqcn,
+                        ),
+                    );
+                }
+            }
+        }
+    }
+
+    /**
+     * Extrait le FQCN (namespace + classe) d'un fichier PHP par lecture du
+     * source, sans charger le fichier.
+     */
+    private function extractFqcn(string $path): ?string
+    {
+        $source = file_get_contents($path);
+        if (false === $source) {
+            return null;
+        }
+
+        if (
+            1 !== preg_match('/^namespace\s+([^;]+);/m', $source, $nsMatch)
+            || 1 !== preg_match('/^(?:final\s+|abstract\s+|readonly\s+)*class\s+(\w+)/m', $source, $classMatch)
+        ) {
+            return null;
+        }
+
+        return trim($nsMatch[1]).'\\'.$classMatch[1];
+    }
+}

tests/Module/Catalog/Api/CategoryListTest.php

@@ -29,7 +29,7 @@ final class CategoryListTest extends AbstractCatalogApiTestCase
         );
 
         $client   = $this->createAdminClient();
-        $response = $client->request('GET', '/api/categories');
+        $response = $client->request('GET', '/api/categories?pagination=false');
         self::assertSame(200, $response->getStatusCode());
 
         $data    = $response->toArray();
@@ -62,7 +62,7 @@ final class CategoryListTest extends AbstractCatalogApiTestCase
         );
 
         $client   = $this->createAdminClient();
-        $response = $client->request('GET', '/api/categories?includeDeleted=true');
+        $response = $client->request('GET', '/api/categories?includeDeleted=true&pagination=false');
         self::assertSame(200, $response->getStatusCode());
 
         $names = array_values(array_filter(
@@ -87,7 +87,7 @@ final class CategoryListTest extends AbstractCatalogApiTestCase
         $this->createCategory(self::TEST_CATEGORY_PREFIX.'mid', $type);
 
         $client   = $this->createAdminClient();
-        $response = $client->request('GET', '/api/categories');
+        $response = $client->request('GET', '/api/categories?pagination=false');
         self::assertSame(200, $response->getStatusCode());
 
         $names = array_values(array_filter(

tests/Module/Catalog/Api/CategoryPaginationTest.php

@@ -0,0 +1,171 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Catalog\Api;
+
+use DateTimeImmutable;
+
+/**
+ * Tests du contrat de pagination sur GET /api/categories (ERP-72).
+ *
+ * Invariants testes :
+ *  - la collection expose les metadonnees Hydra (totalItems, view, member) ;
+ *  - itemsPerPage est plafonne au maximum global (50) ;
+ *  - une page hors limites retourne une collection vide, pas une 500 ;
+ *  - ?pagination=false retourne tous les items sans troncature (select-box) ;
+ *  - la pagination est compatible avec le flag ?includeDeleted=true.
+ *
+ * @internal
+ */
+final class CategoryPaginationTest extends AbstractCatalogApiTestCase
+{
+    /**
+     * La collection expose les metadonnees de pagination JSON-LD sans prefixe :
+     * `totalItems`, `view`, `member` (convention API Platform 4, pas hydra:*).
+     *
+     * On cree 12 categories pour depasser la limite par page (10) : la cle
+     * `view` n'est presente que lorsqu'il y a plus d'items que la taille de page.
+     */
+    public function testCollectionExposesHydraPaginationMetadata(): void
+    {
+        $type = $this->createCategoryType();
+        for ($i = 1; $i <= 12; ++$i) {
+            $this->createCategory(self::TEST_CATEGORY_PREFIX.'meta_'.$i, $type);
+        }
+
+        $client   = $this->createAdminClient();
+        $response = $client->request('GET', '/api/categories');
+
+        self::assertSame(200, $response->getStatusCode());
+
+        $data = $response->toArray();
+        self::assertArrayHasKey('totalItems', $data, 'La collection doit exposer totalItems.');
+        self::assertArrayHasKey('view', $data, 'La collection doit exposer view (pagination) quand totalItems > itemsPerPage.');
+        self::assertIsArray($data['member'], 'member doit etre un tableau.');
+    }
+
+    /**
+     * Un itemsPerPage arbitrairement grand (99999) doit etre plafonne au
+     * maximum global configure (50). On cree 12 categories pour etre certain
+     * de disposer de donnees ; le cap doit s'appliquer quelle que soit la taille
+     * reelle de la collection.
+     */
+    public function testItemsPerPageIsCappedAtMaximum(): void
+    {
+        $type = $this->createCategoryType();
+        for ($i = 1; $i <= 12; ++$i) {
+            $this->createCategory(self::TEST_CATEGORY_PREFIX.'cap_'.$i, $type);
+        }
+
+        $client   = $this->createAdminClient();
+        $response = $client->request('GET', '/api/categories?itemsPerPage=99999');
+
+        self::assertSame(200, $response->getStatusCode());
+        // Le cap global est 50 : jamais plus d'items par page que le maximum.
+        self::assertLessThanOrEqual(
+            50,
+            count($response->toArray()['member']),
+            'itemsPerPage doit etre plafonne au maximum global (50).',
+        );
+    }
+
+    /**
+     * Une page tres elevee (99999) sur une petite collection ne doit pas
+     * produire une 500 PG (OFFSET negatif ou depassement de capacite) mais
+     * retourner 200 avec un tableau member vide.
+     */
+    public function testOutOfBoundPageReturnsEmptyCollectionNot500(): void
+    {
+        $type = $this->createCategoryType();
+        $this->createCategory(self::TEST_CATEGORY_PREFIX.'oob', $type);
+
+        $client   = $this->createAdminClient();
+        $response = $client->request('GET', '/api/categories?page=99999');
+
+        self::assertSame(200, $response->getStatusCode());
+        // La page 99999 est forcement vide (on a bien moins que 99999*10 items).
+        self::assertSame(
+            [],
+            $response->toArray()['member'],
+            'Une page hors limites doit retourner un member vide, jamais une 500.',
+        );
+    }
+
+    /**
+     * ?pagination=false permet au frontend de desactiver la pagination pour
+     * alimenter un select-box. On cree exactement 12 categories dont les noms
+     * commencent par `test_cat_select_` : le filtre sur ce prefixe isole nos
+     * entrees des donnees concurrentes et prouve que les 12 items sont tous
+     * retournes (et pas seulement les 10 premiers de la page 1).
+     */
+    public function testClientCanDisablePaginationToFeedASelect(): void
+    {
+        $type = $this->createCategoryType();
+        for ($i = 1; $i <= 12; ++$i) {
+            $this->createCategory(self::TEST_CATEGORY_PREFIX.'select_'.$i, $type);
+        }
+
+        $client   = $this->createAdminClient();
+        $response = $client->request('GET', '/api/categories?pagination=false');
+
+        self::assertSame(200, $response->getStatusCode());
+
+        $members = $response->toArray()['member'];
+
+        // Filtre sur le sous-prefixe pour ne pas comptabiliser les categories
+        // d'autres tests qui partagent la meme base de donnees.
+        $selectItems = array_values(array_filter(
+            $members,
+            fn (array $m): bool => str_starts_with($m['name'], self::TEST_CATEGORY_PREFIX.'select_'),
+        ));
+
+        self::assertCount(
+            12,
+            $selectItems,
+            '?pagination=false doit retourner toutes les categories (pas seulement la page 1).',
+        );
+    }
+
+    /**
+     * La pagination doit fonctionner conjointement avec le flag ?includeDeleted=true.
+     * On seed 3 categories actives + 2 soft-deleted, on demande itemsPerPage=5 :
+     * la page 1 doit contenir exactement 5 items et totalItems doit valoir >= 5.
+     */
+    public function testPaginationCombinedWithIncludeDeletedFlag(): void
+    {
+        $type = $this->createCategoryType();
+
+        // 3 categories actives.
+        for ($i = 1; $i <= 3; ++$i) {
+            $this->createCategory(self::TEST_CATEGORY_PREFIX.'pag_active_'.$i, $type);
+        }
+
+        // 2 categories soft-deleted.
+        for ($i = 1; $i <= 2; ++$i) {
+            $this->createCategory(
+                self::TEST_CATEGORY_PREFIX.'pag_deleted_'.$i,
+                $type,
+                new DateTimeImmutable(),
+            );
+        }
+
+        $client   = $this->createAdminClient();
+        $response = $client->request('GET', '/api/categories?includeDeleted=true&itemsPerPage=5');
+
+        self::assertSame(200, $response->getStatusCode());
+
+        $data = $response->toArray();
+        // La page retournee ne doit pas exceder itemsPerPage=5.
+        self::assertCount(
+            5,
+            $data['member'],
+            'La page 1 doit contenir exactement 5 items (itemsPerPage=5 avec >= 5 categories disponibles).',
+        );
+        self::assertGreaterThanOrEqual(
+            5,
+            $data['totalItems'],
+            'totalItems doit refleter au moins les 5 categories seedees (actives + soft-deleted).',
+        );
+    }
+}

tests/Module/Core/Api/AuditLogPaginationRegressionTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Api;
+
+/**
+ * Regression test de pagination sur GET /api/audit-logs (ERP-72).
+ *
+ * Avant ce ticket, `paginationItemsPerPage` etait fixe a 30 dans
+ * AuditLogResource. Apres migration vers les defaults globaux (10/50),
+ * ce fichier verrouille le nouveau contrat :
+ *  - la reponse est paginee (max 10 items par page par defaut) ;
+ *  - un itemsPerPage excessif est plafonne a 50.
+ *
+ * Pas de seed : la table audit_log contient deja des lignes issues des
+ * fixtures / autres tests. Les assertions utilisent des inegalites pour
+ * rester robustes quelle que soit la quantite exacte de donnees presentes.
+ *
+ * @internal
+ */
+final class AuditLogPaginationRegressionTest extends AbstractApiTestCase
+{
+    /**
+     * La collection /api/audit-logs doit etre paginee avec les defaults globaux :
+     *  - `member`, `totalItems`, `view` presentes dans la reponse JSON-LD ;
+     *  - au plus 10 items par page (nouveau defaut, etait 30 avant ce ticket).
+     */
+    public function testAuditLogCollectionStillPaginated(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/audit-logs');
+
+        self::assertSame(200, $response->getStatusCode());
+
+        $data = $response->toArray();
+        self::assertArrayHasKey('totalItems', $data, 'La collection audit-logs doit exposer totalItems.');
+        self::assertArrayHasKey('view', $data, 'La collection audit-logs doit exposer view (pagination active).');
+        self::assertIsArray($data['member'], 'member doit etre un tableau.');
+
+        // Le nouveau defaut global est 10 (etait 30 dans AuditLogResource avant ERP-72).
+        self::assertLessThanOrEqual(
+            10,
+            count($data['member']),
+            'La page par defaut ne doit pas depasser 10 items (default global ERP-72).',
+        );
+    }
+
+    /**
+     * Un itemsPerPage excessif (99999) doit etre plafonne au maximum global (50).
+     * Teste la regression specifique du paginator DBAL custom (DbalPaginator) qui
+     * pourrait ignorer la limite si la logique de cap n'est pas appliquee cote provider.
+     */
+    public function testAuditLogItemsPerPageCappedAt50(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/audit-logs?itemsPerPage=99999');
+
+        self::assertSame(200, $response->getStatusCode());
+
+        $data = $response->toArray();
+        self::assertIsArray($data['member'], 'member doit etre un tableau.');
+
+        // Le cap global est 50 : jamais plus d'items par page que le maximum.
+        self::assertLessThanOrEqual(
+            50,
+            count($data['member']),
+            'itemsPerPage=99999 doit etre plafonne a 50 (maximum global ERP-72).',
+        );
+    }
+}

tests/Module/Core/Api/PermissionApiTest.php

@@ -71,11 +71,43 @@ final class PermissionApiTest extends AbstractApiTestCase
         self::assertGreaterThanOrEqual(3, $data['totalItems']);
     }
 
+    /**
+     * Verrouille le chemin paginE PAR DEFAUT (ERP-72) : sans `?pagination=false`,
+     * `/api/permissions` doit borner la page au defaut global (10) et exposer
+     * `view`. Les autres tests de filtre passent `?pagination=false` et
+     * n'exercent donc plus ce contrat — on le reteste ici de maniere isolee.
+     *
+     * On seed 12 permissions de test pour garantir un total > 10 quelle que soit
+     * la quantite de permissions reelles presentes en base.
+     */
+    public function testDefaultCollectionIsPaginatedToGlobalDefault(): void
+    {
+        $em = $this->getEm();
+        for ($i = 1; $i <= 12; ++$i) {
+            $em->persist(new Permission(sprintf('test.core.pagination.perm_%d', $i), sprintf('Perm pagination %d (test)', $i), 'core'));
+        }
+        $em->flush();
+        $em->clear();
+
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/permissions');
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+
+        // La page par defaut ne doit jamais depasser le maximum global (10).
+        self::assertLessThanOrEqual(10, count($data['member']), 'La page par defaut doit etre bornee a 10 items.');
+        // Avec >= 12 permissions de test (+ reelles), le total depasse une page.
+        self::assertGreaterThan(10, $data['totalItems']);
+        // `view` n'est present que lorsque la collection est reellement paginee.
+        self::assertArrayHasKey('view', $data, 'La collection doit exposer view quand totalItems > itemsPerPage.');
+    }
+
     public function testCollectionFilterByModule(): void
     {
         $client   = $this->authenticatedClient('admin', 'admin');
         $response = $client->request('GET', '/api/permissions', [
-            'query' => ['module' => 'core'],
+            'query' => ['module' => 'core', 'pagination' => 'false'],
         ]);
 
         self::assertResponseIsSuccessful();
@@ -94,7 +126,7 @@ final class PermissionApiTest extends AbstractApiTestCase
     {
         $client   = $this->authenticatedClient('admin', 'admin');
         $response = $client->request('GET', '/api/permissions', [
-            'query' => ['orphan' => 'true'],
+            'query' => ['orphan' => 'true', 'pagination' => 'false'],
         ]);
 
         self::assertResponseIsSuccessful();
@@ -114,7 +146,7 @@ final class PermissionApiTest extends AbstractApiTestCase
     {
         $client   = $this->authenticatedClient('admin', 'admin');
         $response = $client->request('GET', '/api/permissions', [
-            'query' => ['orphan' => 'false'],
+            'query' => ['orphan' => 'false', 'pagination' => 'false'],
         ]);
 
         self::assertResponseIsSuccessful();

tests/Module/Core/Api/RoleApiTest.php

@@ -146,7 +146,7 @@ final class RoleApiTest extends AbstractApiTestCase
     public function testGetCollectionAsAdminReturnsRoles(): void
     {
         $client   = $this->authenticatedClient('admin', 'admin');
-        $response = $client->request('GET', '/api/roles');
+        $response = $client->request('GET', '/api/roles?pagination=false');
 
         self::assertResponseIsSuccessful();
         $data = $response->toArray();
@@ -157,6 +157,35 @@ final class RoleApiTest extends AbstractApiTestCase
         self::assertContains('test_editor', $codes);
     }
 
+    /**
+     * Verrouille le chemin paginE PAR DEFAUT (ERP-72) : le test ci-dessus passe
+     * `?pagination=false` (usage <select>) et n'exerce donc plus le defaut
+     * paginE. On seed 11 roles de test pour depasser une page (10) et verifier
+     * que, sans parametre, la page est bornee a 10 et expose `view`.
+     */
+    public function testDefaultCollectionIsPaginatedToGlobalDefault(): void
+    {
+        $em = $this->getEm();
+        for ($i = 1; $i <= 11; ++$i) {
+            $em->persist(new Role(sprintf('test_pg_%d', $i), sprintf('Role pagination %d (test)', $i), false));
+        }
+        $em->flush();
+        $em->clear();
+
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/roles');
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+
+        // La page par defaut ne doit jamais depasser le maximum global (10).
+        self::assertLessThanOrEqual(10, count($data['member']), 'La page par defaut doit etre bornee a 10 items.');
+        // 11 roles de test + 2 systeme + editor + viewer => total > 10.
+        self::assertGreaterThan(10, $data['totalItems']);
+        // `view` n'est present que lorsque la collection est reellement paginee.
+        self::assertArrayHasKey('view', $data, 'La collection doit exposer view quand totalItems > itemsPerPage.');
+    }
+
     public function testGetCollectionFilterByIsSystemTrue(): void
     {
         $client   = $this->authenticatedClient('admin', 'admin');