[ERP-55] ClientProvider + ClientProcessor + RG métier (M1) — stackée sur ERP-54 (#31)

**MR stackée sur ERP-54** — cible = `feature/ERP-54-creer-entites-client-m1` (PAS `develop`). Tristan validera le stack en fin de chaîne. Branche l'API REST du répertoire clients (M1) sur l'entité `Client` d'ERP-54. ## Périmètre - **ClientProvider** : liste paginée (Paginator ORM aligné ERP-72, `?pagination=false`), exclusion archives+soft-delete par défaut (RG-1.24), `?includeArchived=true` (RG-1.25), tri `companyName ASC` (RG-1.26), filtres `?search` (fuzzy) + `?categoryType`, détail 404 si soft-deleted + embarque contacts/adresses/ribs. - **ClientProcessor** : normalisation (RG-1.18→1.21), 409 doublon nom (RG-1.16) + 409 restauration (RG-1.23), gating par onglet `accounting.manage`/`archive` + mode strict 403 (RG-1.28), archivage exclusif + `archivedAt` (RG-1.22), RG-1.01 / RG-1.03 (mutex + type catégorie) / RG-1.12 / RG-1.13 / RG-1.04. - **ClientReadGroupContextBuilder** : ajout conditionnel du groupe `client:read:accounting` selon `commercial.clients.accounting.view`. - **CategoryReferenceDenormalizer** : résout les IRI catégorie vers `Category` (dénormalisation impossible sur l'interface sinon). - **Contrats Shared** : `CategoryInterface::getCategoryTypeCode()`, `BusinessRoleAwareInterface` + `BusinessRoles::COMMERCIALE`. ## Coordination stack - Permissions `commercial.clients.*` **référencées** ici, déclarées en **ERP-59** (tests RBAC en **ERP-60**). - Rôle métier `commerciale` seedé par **ERP-74** (RG-1.04 dormante d'ici là). - Config globale pagination (itemsPerPage client / max 50) portée par **ERP-72**. - Référentiels comptables (PaymentType/Bank/...) exposés en **ERP-56** → RG-1.12/1.13 testées en unitaire ici (pas d'IRI référentiel disponible avant ERP-56). ## Tests 31 tests Commercial (intégration admin sur les RG métier + unitaires sur le gating / RG-1.04 / RG-1.12 / RG-1.13 / context builder). Suite complète verte (343 tests). Règle n°1 respectée (aucun import inter-modules dans Commercial). --------- Co-authored-by: tristan <tristan@yuno.malio.fr> Co-authored-by: Matthieu <contact@malio.fr> Co-authored-by: Matthieu <mtholot19@gmail.com> Reviewed-on: #31 Co-authored-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr> Co-committed-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
2026-06-01 19:28:04 +00:00
parent b495e4030a
commit 0c9b563cae
18 changed files with 2085 additions and 4 deletions
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Commercial\Unit;
+
+use ApiPlatform\Metadata\IriConverterInterface;
+use App\Module\Commercial\Infrastructure\ApiPlatform\Serializer\CategoryReferenceDenormalizer;
+use App\Shared\Domain\Contract\CategoryInterface;
+use PHPUnit\Framework\TestCase;
+use stdClass;
+use Symfony\Component\Serializer\Exception\UnexpectedValueException;
+
+/**
+ * Tests unitaires du CategoryReferenceDenormalizer : resolution d'un IRI vers
+ * une Category concrete, et rejet explicite d'un IRI pointant sur une autre
+ * ressource (au lieu d'un null silencieux qui perdrait la reference).
+ *
+ * @internal
+ */
+final class CategoryReferenceDenormalizerTest extends TestCase
+{
+    public function testResolvesCategoryIri(): void
+    {
+        $category     = $this->createStub(CategoryInterface::class);
+        $iriConverter = $this->createMock(IriConverterInterface::class);
+        $iriConverter->method('getResourceFromIri')->willReturn($category);
+
+        $denormalizer = new CategoryReferenceDenormalizer($iriConverter);
+
+        self::assertSame(
+            $category,
+            $denormalizer->denormalize('/api/categories/1', CategoryInterface::class),
+        );
+    }
+
+    public function testRejectsIriOfWrongType(): void
+    {
+        // Bug review ERP-55 : un IRI syntaxiquement valide mais pointant sur une
+        // autre ressource (ex: /api/clients/5) doit lever une exception au lieu
+        // d'etre silencieusement ignore.
+        $iriConverter = $this->createMock(IriConverterInterface::class);
+        $iriConverter->method('getResourceFromIri')->willReturn(new stdClass());
+
+        $denormalizer = new CategoryReferenceDenormalizer($iriConverter);
+
+        $this->expectException(UnexpectedValueException::class);
+        $denormalizer->denormalize('/api/clients/5', CategoryInterface::class);
+    }
+
+    public function testReturnsNullForEmptyData(): void
+    {
+        // Valeur vide deleguee par l'ArrayDenormalizer : aucun appel a
+        // l'IriConverter, retour null.
+        $iriConverter = $this->createMock(IriConverterInterface::class);
+        $iriConverter->expects(self::never())->method('getResourceFromIri');
+
+        $denormalizer = new CategoryReferenceDenormalizer($iriConverter);
+
+        self::assertNull($denormalizer->denormalize('', CategoryInterface::class));
+    }
+}
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Commercial\Unit;
+
+use App\Module\Commercial\Application\Service\ClientFieldNormalizer;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests unitaires de la normalisation serveur (RG-1.18 a RG-1.21).
+ *
+ * @internal
+ */
+final class ClientFieldNormalizerTest extends TestCase
+{
+    private ClientFieldNormalizer $normalizer;
+
+    protected function setUp(): void
+    {
+        $this->normalizer = new ClientFieldNormalizer();
+    }
+
+    public function testCompanyNameIsUppercased(): void
+    {
+        // RG-1.18
+        self::assertSame('ACME SAS', $this->normalizer->normalizeCompanyName('  acme sas '));
+        self::assertNull($this->normalizer->normalizeCompanyName(null));
+    }
+
+    public function testPersonNameIsTitleCased(): void
+    {
+        // RG-1.19
+        self::assertSame('Jean', $this->normalizer->normalizePersonName('JEAN'));
+        self::assertSame('Dupont', $this->normalizer->normalizePersonName('dupont'));
+        self::assertNull($this->normalizer->normalizePersonName('   '));
+        self::assertNull($this->normalizer->normalizePersonName(null));
+    }
+
+    public function testEmailIsLowercased(): void
+    {
+        // RG-1.21
+        self::assertSame('jean.dupont@acme.fr', $this->normalizer->normalizeEmail(' Jean.DUPONT@ACME.FR '));
+        self::assertNull($this->normalizer->normalizeEmail(null));
+        self::assertNull($this->normalizer->normalizeEmail('   '));
+    }
+
+    public function testPhoneKeepsOnlyDigits(): void
+    {
+        // RG-1.20
+        self::assertSame('0612345678', $this->normalizer->normalizePhone('06.12.34.56.78'));
+        self::assertSame('0612345678', $this->normalizer->normalizePhone('06 12 34 56 78'));
+        self::assertNull($this->normalizer->normalizePhone('----'));
+        self::assertNull($this->normalizer->normalizePhone(null));
+    }
+}
@@ -0,0 +1,354 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Commercial\Unit;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use ApiPlatform\Validator\Exception\ValidationException;
+use App\Module\Commercial\Application\Service\ClientFieldNormalizer;
+use App\Module\Commercial\Application\Validator\ClientInformationCompletenessValidator;
+use App\Module\Commercial\Domain\Entity\Bank;
+use App\Module\Commercial\Domain\Entity\Client;
+use App\Module\Commercial\Domain\Entity\ClientRib;
+use App\Module\Commercial\Domain\Entity\PaymentType;
+use App\Module\Commercial\Infrastructure\ApiPlatform\State\Processor\ClientProcessor;
+use App\Shared\Domain\Contract\BusinessRoleAwareInterface;
+use App\Shared\Domain\Security\BusinessRoles;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\UnitOfWork;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException;
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Tests unitaires du ClientProcessor : gating par permission (accounting.manage
+ * / archive / RG-1.28 strict) et regles metier non testables en HTTP admin
+ * (RG-1.04 Commerciale, RG-1.12 Virement, RG-1.13 LCR), grace a un Security et
+ * un RequestStack stubbes.
+ *
+ * @internal
+ */
+final class ClientProcessorTest extends TestCase
+{
+    public function testAccountingFieldWithoutPermissionIsForbidden(): void
+    {
+        // RG-1.28 : la modification effective d'un champ comptable sans
+        // accounting.manage -> 403. En creation (POST), positionner siren est un
+        // changement vs l'etat persiste vide.
+        $client = $this->minimalClient();
+        $client->setSiren('123456789');
+
+        $processor = $this->makeProcessor(granted: [], payload: ['siren' => '123456789']);
+
+        $this->expectException(AccessDeniedHttpException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testStrictMixWithAccountingFieldIsForbidden(): void
+    {
+        // RG-1.28 : payload mixant main + accounting sans la permission -> 403
+        // sur l'ensemble (pas de filtrage silencieux).
+        $client = $this->minimalClient();
+        $client->setCompanyName('X');
+        $client->setSiren('123456789');
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: ['companyName' => 'X', 'siren' => '123456789'],
+        );
+
+        $this->expectException(AccessDeniedHttpException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testArchiveWithoutPermissionIsForbidden(): void
+    {
+        // RG-1.22 : basculer isArchived sans la permission archive -> 403.
+        $client = $this->minimalClient();
+        $client->setIsArchived(true);
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: ['isArchived' => true],
+            managed: true,
+            originalData: ['isArchived' => false],
+        );
+
+        $this->expectException(AccessDeniedHttpException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testArchiveWithOtherFieldIsUnprocessable(): void
+    {
+        // RG-1.22 : une requete d'archivage ne modifie aucun autre champ.
+        $client = $this->minimalClient();
+        $client->setIsArchived(true);
+        $client->setCompanyName('X');
+
+        $processor = $this->makeProcessor(
+            granted: ['commercial.clients.archive'],
+            payload: ['isArchived' => true, 'companyName' => 'X'],
+            managed: true,
+            originalData: ['isArchived' => false],
+        );
+
+        $this->expectException(UnprocessableEntityHttpException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testPostWithIsArchivedFalseIsNotGated(): void
+    {
+        // Bug review ERP-55 : un POST renvoyant isArchived:false (valeur par
+        // defaut) ne doit declencher ni 403 (archive) ni 422, meme sans
+        // permission. L'entite n'est pas encore geree par l'ORM.
+        $client = $this->minimalClient(); // isArchived = false par defaut
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: ['companyName' => 'Test Co', 'isArchived' => false],
+            managed: false,
+        );
+
+        self::assertInstanceOf(Client::class, $processor->process($client, $this->operation()));
+    }
+
+    public function testFullRepresentationPatchWithUnchangedArchiveIsNotGated(): void
+    {
+        // Bug review ERP-55 : un PATCH « representation complete » renvoyant
+        // isArchived inchange + des cles JSON-LD (@id, @context) ne doit pas etre
+        // gate (ni 403 archive ni 422), meme sans permission.
+        $client = $this->minimalClient(); // isArchived = false (inchange)
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: [
+                '@id'         => '/api/clients/1',
+                '@context'    => '/api/contexts/Client',
+                'companyName' => 'Test Co',
+                'isArchived'  => false,
+            ],
+            managed: true,
+            originalData: ['isArchived' => false],
+        );
+
+        self::assertInstanceOf(Client::class, $processor->process($client, $this->operation()));
+    }
+
+    public function testUnchangedAccountingFieldOnPatchIsNotGated(): void
+    {
+        // Bug review ERP-55 : renvoyer un champ comptable a sa valeur persistee
+        // (PATCH representation complete) ne change rien -> pas d'exigence
+        // accounting.manage.
+        $client = $this->minimalClient();
+        $client->setSiren('123456789'); // identique a l'etat persiste
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: ['companyName' => 'Test Co', 'siren' => '123456789'],
+            managed: true,
+            // getOriginalEntityData renvoie tous les champs mappes d'une entite
+            // geree : isArchived (non-null) y figure toujours.
+            originalData: ['siren' => '123456789', 'isArchived' => false],
+        );
+
+        self::assertInstanceOf(Client::class, $processor->process($client, $this->operation()));
+    }
+
+    public function testVirementWithoutBankIsUnprocessable(): void
+    {
+        // RG-1.12
+        $client = $this->minimalClient();
+        $client->setPaymentType($this->paymentType('VIREMENT'));
+
+        $processor = $this->makeProcessor(
+            granted: ['commercial.clients.accounting.manage'],
+            payload: ['paymentType' => '/api/payment_types/1'],
+        );
+
+        $this->expectException(ValidationException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testVirementWithBankPasses(): void
+    {
+        // RG-1.12 satisfait : Virement + banque.
+        $client = $this->minimalClient();
+        $client->setPaymentType($this->paymentType('VIREMENT'));
+        $client->setBank(new Bank());
+
+        $processor = $this->makeProcessor(
+            granted: ['commercial.clients.accounting.manage'],
+            payload: ['paymentType' => '/api/payment_types/1', 'bank' => '/api/banks/1'],
+        );
+
+        $result = $processor->process($client, $this->operation());
+        self::assertInstanceOf(Client::class, $result);
+    }
+
+    public function testLcrWithoutRibIsUnprocessable(): void
+    {
+        // RG-1.13
+        $client = $this->minimalClient();
+        $client->setPaymentType($this->paymentType('LCR'));
+
+        $processor = $this->makeProcessor(
+            granted: ['commercial.clients.accounting.manage'],
+            payload: ['paymentType' => '/api/payment_types/2'],
+        );
+
+        $this->expectException(ValidationException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testLcrWithRibPasses(): void
+    {
+        // RG-1.13 satisfait : LCR + au moins un RIB.
+        $client = $this->minimalClient();
+        $client->setPaymentType($this->paymentType('LCR'));
+        $client->addRib(new ClientRib());
+
+        $processor = $this->makeProcessor(
+            granted: ['commercial.clients.accounting.manage'],
+            payload: ['paymentType' => '/api/payment_types/2'],
+        );
+
+        self::assertInstanceOf(Client::class, $processor->process($client, $this->operation()));
+    }
+
+    public function testCommercialeIncompleteInformationIsUnprocessable(): void
+    {
+        // RG-1.04 : role Commerciale + onglet Information incomplet -> 422.
+        $client = $this->minimalClient();
+        $client->setDescription('Une description'); // les autres champs Information restent null
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: ['description' => 'Une description'],
+            user: $this->commercialeUser(),
+        );
+
+        $this->expectException(ValidationException::class);
+        $processor->process($client, $this->operation());
+    }
+
+    public function testNonCommercialeSkipsInformationCompleteness(): void
+    {
+        // Meme payload incomplet, mais user non-Commerciale -> aucun blocage.
+        $client = $this->minimalClient();
+        $client->setDescription('Une description');
+
+        $processor = $this->makeProcessor(
+            granted: [],
+            payload: ['description' => 'Une description'],
+            user: null,
+        );
+
+        self::assertInstanceOf(Client::class, $processor->process($client, $this->operation()));
+    }
+
+    /**
+     * @param list<string>         $granted      Permissions accordees a l'utilisateur courant
+     * @param array<string, mixed> $payload      Corps JSON simule de la requete
+     * @param bool                 $managed      true = entite geree par l'ORM (PATCH), false = creation (POST)
+     * @param array<string, mixed> $originalData Etat persiste simule (getOriginalEntityData) pour la detection de changement
+     */
+    private function makeProcessor(
+        array $granted,
+        array $payload,
+        ?UserInterface $user = null,
+        bool $managed = false,
+        array $originalData = [],
+    ): ClientProcessor {
+        $persist = new class implements ProcessorInterface {
+            public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+            {
+                return $data;
+            }
+        };
+
+        $security = $this->createStub(Security::class);
+        $security->method('isGranted')->willReturnCallback(
+            static fn (mixed $attribute): bool => is_string($attribute) && in_array($attribute, $granted, true),
+        );
+        $security->method('getUser')->willReturn($user);
+
+        $requestStack = new RequestStack();
+        $requestStack->push(new Request([], [], [], [], [], [], json_encode($payload, JSON_THROW_ON_ERROR)));
+
+        // EntityManager stub : contains() distingue creation (POST) et mise a
+        // jour (PATCH) ; getOriginalEntityData() fournit l'etat persiste compare
+        // par le gating (RG-1.22 / RG-1.28).
+        $uow = $this->createMock(UnitOfWork::class);
+        $uow->method('getOriginalEntityData')->willReturn($originalData);
+
+        $em = $this->createMock(EntityManagerInterface::class);
+        $em->method('contains')->willReturn($managed);
+        $em->method('getUnitOfWork')->willReturn($uow);
+
+        return new ClientProcessor(
+            $persist,
+            new ClientFieldNormalizer(),
+            new ClientInformationCompletenessValidator(),
+            $security,
+            $requestStack,
+            $em,
+        );
+    }
+
+    /**
+     * Client minimal valide vis-a-vis de RG-1.01 (un nom de contact) — suffisant
+     * pour atteindre les validations testees.
+     */
+    private function minimalClient(): Client
+    {
+        $client = new Client();
+        $client->setCompanyName('Test Co');
+        $client->setLastName('Dupont');
+        $client->setPhonePrimary('0102030405');
+        $client->setEmail('t@test.fr');
+
+        return $client;
+    }
+
+    private function paymentType(string $code): PaymentType
+    {
+        $type = new PaymentType();
+        $type->setCode($code);
+        $type->setLabel($code);
+
+        return $type;
+    }
+
+    private function operation(): Operation
+    {
+        return $this->createStub(Operation::class);
+    }
+
+    private function commercialeUser(): UserInterface
+    {
+        return new class implements UserInterface, BusinessRoleAwareInterface {
+            public function hasBusinessRole(string $roleCode): bool
+            {
+                return BusinessRoles::COMMERCIALE === $roleCode;
+            }
+
+            public function getRoles(): array
+            {
+                return ['ROLE_USER'];
+            }
+
+            public function eraseCredentials(): void {}
+
+            public function getUserIdentifier(): string
+            {
+                return 'commerciale-test';
+            }
+        };
+    }
+}
@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Commercial\Unit;
+
+use ApiPlatform\State\SerializerContextBuilderInterface;
+use App\Module\Commercial\Domain\Entity\Client;
+use App\Module\Commercial\Infrastructure\ApiPlatform\Serializer\ClientReadGroupContextBuilder;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\HttpFoundation\Request;
+
+/**
+ * Tests unitaires du context builder qui ajoute conditionnellement le groupe
+ * de lecture `client:read:accounting` selon la permission accounting.view
+ * (§ 2.7 / § 4.1 / § 4.2).
+ *
+ * @internal
+ */
+final class ClientReadGroupContextBuilderTest extends TestCase
+{
+    public function testAddsAccountingGroupForClientReadWhenGranted(): void
+    {
+        $builder = $this->builder(
+            baseContext: ['resource_class' => Client::class, 'groups' => ['client:read', 'default:read']],
+            granted: true,
+        );
+
+        $context = $builder->createFromRequest(new Request(), true);
+
+        self::assertContains('client:read:accounting', $context['groups']);
+    }
+
+    public function testDoesNotAddAccountingGroupWhenNotGranted(): void
+    {
+        $builder = $this->builder(
+            baseContext: ['resource_class' => Client::class, 'groups' => ['client:read', 'default:read']],
+            granted: false,
+        );
+
+        $context = $builder->createFromRequest(new Request(), true);
+
+        self::assertNotContains('client:read:accounting', $context['groups']);
+    }
+
+    public function testDoesNotAddAccountingGroupOnWrite(): void
+    {
+        $builder = $this->builder(
+            baseContext: ['resource_class' => Client::class, 'groups' => ['client:write:main']],
+            granted: true,
+        );
+
+        // normalization = false -> ecriture : pas de groupe de lecture ajoute.
+        $context = $builder->createFromRequest(new Request(), false);
+
+        self::assertNotContains('client:read:accounting', $context['groups']);
+    }
+
+    public function testIgnoresOtherResources(): void
+    {
+        $builder = $this->builder(
+            baseContext: ['resource_class' => 'App\Other\Resource', 'groups' => ['other:read']],
+            granted: true,
+        );
+
+        $context = $builder->createFromRequest(new Request(), true);
+
+        self::assertSame(['other:read'], $context['groups']);
+    }
+
+    /**
+     * @param array<string, mixed> $baseContext
+     */
+    private function builder(array $baseContext, bool $granted): ClientReadGroupContextBuilder
+    {
+        $decorated = $this->createStub(SerializerContextBuilderInterface::class);
+        $decorated->method('createFromRequest')->willReturn($baseContext);
+
+        $security = $this->createStub(Security::class);
+        $security->method('isGranted')->willReturn($granted);
+
+        return new ClientReadGroupContextBuilder($decorated, $security);
+    }
+}