feat(transport) : sous-ressource adresses transporteur (ERP-159)

POST /api/carriers/{id}/addresses + PATCH/DELETE /api/carrier_addresses/{id}
(security transport.carriers.manage), spec-back § 4.5. Jumelle de SupplierAddress
(M2) / ProviderAddress (M3), sans address_type ni M2M.

- CarrierAddress : ajout #[ApiResource] (Get/Post/Patch/Delete) + groupe
  d'ecriture carrier:write:addresses + contraintes FR. RG-4.06 : code postal
  ^[0-9]{4,5}$ (Assert\Regex). Mapping ORM/colonnes inchange.
- CarrierAddressProcessor : rattachement parent (404 si absent) + RG-4.05
  (transporteur affrete -> Pays/CP/Ville/Adresse obligatoires, 422 par champ).
  RG-4.05 portee par le processor car le parent est indisponible a la validation
  Symfony sur un POST sous-ressource read:false. RG-4.07 = front (PATCH accepte).
- EXCLUDED_LENGTH_MIRROR : CarrierAddress::postalCode (Regex borne la longueur).
- Tests : CP invalide 422, affrete incomplet 422, affrete complet 201,
  PATCH/DELETE OK (manage), 403 sans manage.

src/Module/Transport/Domain/Entity/CarrierAddress.php

@@ -4,22 +4,86 @@ declare(strict_types=1);
 
 namespace App\Module\Transport\Domain\Entity;
 
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Link;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
+use App\Module\Transport\Infrastructure\ApiPlatform\State\Processor\CarrierAddressProcessor;
 use App\Shared\Domain\Attribute\Auditable;
 use App\Shared\Domain\Contract\BlamableInterface;
 use App\Shared\Domain\Contract\TimestampableInterface;
 use App\Shared\Domain\Trait\TimestampableBlamableTrait;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\Serializer\Attribute\Groups;
+use Symfony\Component\Validator\Constraints as Assert;
 
 /**
  * Adresse d'un transporteur (1:n) — onglet Adresse (M4). Jumelle de
  * SupplierAddress (M2), version simplifiee (pas de type d'adresse, pas de M2M
  * sites/categories sur l'adresse : les sites du M4 vivent dans l'onglet Prix).
  *
- * WT3 (ERP-155/157) = LECTURE seule : proprietes en `carrier:item:read`
+ * Lecture : proprietes en `carrier:item:read` (embarquees au detail du
- * (embarquees au detail du transporteur). Les sous-ressources d'ecriture
+ * transporteur). Ecriture : groupe `carrier:write:addresses`.
- * (POST/PATCH/DELETE) + RG-4.05→4.07 arrivent au worktree dedie (WT6).
+ *
+ * Sous-ressource API (ERP-159, spec § 4.5) — jumelle de SupplierAddress (M2) /
+ * ProviderAddress (M3), sans address_type ni M2M (les sites du M4 vivent dans
+ * l'onglet Prix) :
+ *  - POST /api/carriers/{carrierId}/addresses : creation rattachee au
+ *    transporteur parent (Link toProperty 'carrier'), security
+ *    transport.carriers.manage.
+ *  - PATCH / DELETE /api/carrier_addresses/{id} : security
+ *    transport.carriers.manage.
+ *  - GET /api/carrier_addresses/{id} : lecture unitaire (security view) — la
+ *    lecture courante reste via le parent. Pas de GET collection autonome.
+ * Tout passe par le CarrierAddressProcessor (rattachement parent + RG-4.05).
+ *
+ * Regles de l'onglet Adresse :
+ *  - RG-4.06 : code postal a 4 ou 5 chiffres (Assert\Regex ; pas de controle
+ *    CP/ville serveur, l'autocomplete BAN est front).
+ *  - RG-4.05 : si le transporteur est affrete (isChartered), l'adresse devient
+ *    obligatoire (Pays / CP / Ville / Adresse) — validation conditionnelle portee
+ *    par le CarrierAddressProcessor (le parent n'est pas disponible a la
+ *    validation Symfony sur un POST sous-ressource en read:false).
+ *  - RG-4.07 : masquage du bouton « Valider » si QUALIMAT = front ; le back
+ *    accepte le PATCH normalement (aucune garde back specifique).
+ *
+ * Audite (#[Auditable]) + Timestampable / Blamable.
  */
+#[ApiResource(
+    operations: [
+        new Get(
+            security: "is_granted('transport.carriers.view')",
+            normalizationContext: ['groups' => ['carrier:item:read', 'default:read']],
+        ),
+        new Post(
+            uriTemplate: '/carriers/{carrierId}/addresses',
+            uriVariables: [
+                'carrierId' => new Link(fromClass: Carrier::class, toProperty: 'carrier'),
+            ],
+            // read:false : pas de stade lecture du parent. Le Link toProperty
+            // resoudrait l'enfant (SELECT CarrierAddress ... WHERE carrier = :id)
+            // et casse en NonUniqueResult des >= 2 enfants. Le parent est rattache
+            // manuellement par CarrierAddressProcessor::linkParent (404 si absent).
+            read: false,
+            security: "is_granted('transport.carriers.manage')",
+            normalizationContext: ['groups' => ['carrier:item:read', 'default:read']],
+            denormalizationContext: ['groups' => ['carrier:write:addresses']],
+            processor: CarrierAddressProcessor::class,
+        ),
+        new Patch(
+            security: "is_granted('transport.carriers.manage')",
+            normalizationContext: ['groups' => ['carrier:item:read', 'default:read']],
+            denormalizationContext: ['groups' => ['carrier:write:addresses']],
+            processor: CarrierAddressProcessor::class,
+        ),
+        new Delete(
+            security: "is_granted('transport.carriers.manage')",
+            processor: CarrierAddressProcessor::class,
+        ),
+    ],
+)]
 #[ORM\Entity]
 #[ORM\Table(name: 'carrier_address')]
 #[ORM\Index(name: 'idx_carrier_address_carrier', columns: ['carrier_id'])]
@@ -41,23 +105,32 @@ class CarrierAddress implements TimestampableInterface, BlamableInterface
     private ?Carrier $carrier = null;
 
     #[ORM\Column(length: 80, options: ['default' => 'France'])]
-    #[Groups(['carrier:item:read'])]
+    #[Assert\Length(max: 80, maxMessage: 'Le pays ne peut dépasser {{ limit }} caractères.', normalizer: 'trim')]
+    #[Groups(['carrier:item:read', 'carrier:write:addresses'])]
     private string $country = 'France';
 
+    // RG-4.06 : code postal a 4 ou 5 chiffres (pas de controle CP/ville serveur,
+    // l'autocomplete BAN est front). Le Regex borne deja la longueur (<= 5) : pas
+    // de Length redondant (whitelist EXCLUDED_LENGTH_MIRROR). Nullable : obligatoire
+    // seulement si affrete (RG-4.05, garde CarrierAddressProcessor).
     #[ORM\Column(name: 'postal_code', length: 20, nullable: true)]
-    #[Groups(['carrier:item:read'])]
+    #[Assert\Regex(pattern: '/^[0-9]{4,5}$/', message: 'Le code postal doit comporter 4 ou 5 chiffres.')]
+    #[Groups(['carrier:item:read', 'carrier:write:addresses'])]
     private ?string $postalCode = null;
 
     #[ORM\Column(length: 120, nullable: true)]
-    #[Groups(['carrier:item:read'])]
+    #[Assert\Length(max: 120, maxMessage: 'La ville ne peut dépasser {{ limit }} caractères.', normalizer: 'trim')]
+    #[Groups(['carrier:item:read', 'carrier:write:addresses'])]
     private ?string $city = null;
 
     #[ORM\Column(length: 255, nullable: true)]
-    #[Groups(['carrier:item:read'])]
+    #[Assert\Length(max: 255, maxMessage: 'L\'adresse ne peut dépasser {{ limit }} caractères.', normalizer: 'trim')]
+    #[Groups(['carrier:item:read', 'carrier:write:addresses'])]
     private ?string $street = null;
 
     #[ORM\Column(name: 'street_complement', length: 255, nullable: true)]
-    #[Groups(['carrier:item:read'])]
+    #[Assert\Length(max: 255, maxMessage: 'Le complément d\'adresse ne peut dépasser {{ limit }} caractères.', normalizer: 'trim')]
+    #[Groups(['carrier:item:read', 'carrier:write:addresses'])]
     private ?string $streetComplement = null;
 
     #[ORM\Column(options: ['default' => 0])]

src/Module/Transport/Infrastructure/ApiPlatform/State/Processor/CarrierAddressProcessor.php

@@ -0,0 +1,134 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Transport\Infrastructure\ApiPlatform\State\Processor;
+
+use ApiPlatform\Metadata\DeleteOperationInterface;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use ApiPlatform\Validator\Exception\ValidationException;
+use App\Module\Transport\Domain\Entity\Carrier;
+use App\Module\Transport\Domain\Entity\CarrierAddress;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Symfony\Component\Validator\ConstraintViolation;
+use Symfony\Component\Validator\ConstraintViolationList;
+
+/**
+ * Processor d'ecriture de la sous-ressource Adresse d'un transporteur (M4,
+ * spec-back § 4.5). Jumeau du SupplierAddressProcessor (M2) / ProviderAddressProcessor
+ * (M3), recentre sur le perimetre ERP-159, AVEC une garde propre au M4 : RG-4.05
+ * (adresse obligatoire si le transporteur est affrete).
+ *
+ * Sequence :
+ *  - POST / PATCH : rattachement au transporteur parent (linkParent) puis garde
+ *    RG-4.05 (guardCharteredAddress). RG-4.06 (code postal, Assert\Regex) est portee
+ *    par l'entite et jouee par API Platform AVANT ce processor.
+ *  - DELETE : aucune regle metier specifique (suppression physique directe).
+ *
+ * RG-4.05 vit ICI (et non en Assert\Callback sur l'entite) car elle depend du
+ * transporteur PARENT, indisponible a la validation Symfony sur un POST
+ * sous-ressource en read:false (le parent n'est rattache qu'au stade processor).
+ * La violation est construite a la main avec le meme rendu Hydra que les
+ * contraintes Symfony, donc consommable inline par champ (convention ERP-101).
+ *
+ * RG-4.07 (masquage du bouton « Valider » si QUALIMAT) est purement front : le
+ * back accepte le PATCH normalement, aucune garde ici.
+ *
+ * La security d'operation (transport.carriers.manage) est appliquee par API
+ * Platform en amont, de meme que la validation Symfony des contraintes d'attribut.
+ *
+ * @implements ProcessorInterface<CarrierAddress, null|CarrierAddress>
+ */
+final class CarrierAddressProcessor implements ProcessorInterface
+{
+    public function __construct(
+        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
+        private readonly ProcessorInterface $persistProcessor,
+        #[Autowire(service: 'api_platform.doctrine.orm.state.remove_processor')]
+        private readonly ProcessorInterface $removeProcessor,
+        private readonly EntityManagerInterface $em,
+    ) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+    {
+        if (!$data instanceof CarrierAddress) {
+            return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
+        }
+
+        if ($operation instanceof DeleteOperationInterface) {
+            return $this->removeProcessor->process($data, $operation, $uriVariables, $context);
+        }
+
+        $this->linkParent($data, $uriVariables);
+        $this->guardCharteredAddress($data);
+
+        return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
+    }
+
+    /**
+     * Rattache l'adresse au transporteur parent de la sous-ressource POST
+     * (/carriers/{carrierId}/addresses) : la relation n'est pas peuplee
+     * automatiquement par le Link sur une ecriture. Sur PATCH, no-op.
+     */
+    private function linkParent(CarrierAddress $address, array $uriVariables): void
+    {
+        if (null !== $address->getCarrier()) {
+            return;
+        }
+
+        $carrierId = $uriVariables['carrierId'] ?? null;
+        if (null === $carrierId) {
+            return;
+        }
+
+        $carrier = $carrierId instanceof Carrier
+            ? $carrierId
+            : $this->em->getRepository(Carrier::class)->find($carrierId);
+
+        // read:false sur le POST : sans stade lecture, un parent introuvable n'est
+        // plus intercepte en amont -> 404 explicite (sinon 500 au persist sur la
+        // contrainte carrier_id NOT NULL).
+        if (!$carrier instanceof Carrier) {
+            throw new NotFoundHttpException('Transporteur introuvable.');
+        }
+
+        $address->setCarrier($carrier);
+    }
+
+    /**
+     * RG-4.05 : si le transporteur parent est affrete (isChartered), l'adresse doit
+     * porter Pays / Code postal / Ville / Adresse. Chaque champ manquant -> une
+     * violation 422 sur son propre propertyPath (mapping inline ERP-101). La
+     * validation porte sur l'ETAT RESULTANT de l'adresse (apres application du
+     * payload), donc identique sur POST et sur PATCH partiel. Sans affretement,
+     * l'adresse reste partielle (champs nullable, RG-4.06 inchangee).
+     */
+    private function guardCharteredAddress(CarrierAddress $address): void
+    {
+        $carrier = $address->getCarrier();
+        if (!$carrier instanceof Carrier || !$carrier->isChartered()) {
+            return;
+        }
+
+        $required = [
+            'country'    => [$address->getCountry(), 'Le pays est obligatoire pour un transporteur affrété.'],
+            'postalCode' => [$address->getPostalCode(), 'Le code postal est obligatoire pour un transporteur affrété.'],
+            'city'       => [$address->getCity(), 'La ville est obligatoire pour un transporteur affrété.'],
+            'street'     => [$address->getStreet(), 'L\'adresse est obligatoire pour un transporteur affrété.'],
+        ];
+
+        $violations = new ConstraintViolationList();
+        foreach ($required as $path => [$value, $message]) {
+            if (null === $value || '' === trim($value)) {
+                $violations->add(new ConstraintViolation($message, null, [], $address, $path, $value));
+            }
+        }
+
+        if (0 < $violations->count()) {
+            throw new ValidationException($violations);
+        }
+    }
+}

tests/Architecture/EntityConstraintsHaveFrenchMessageTest.php

@@ -56,6 +56,8 @@ final class EntityConstraintsHaveFrenchMessageTest extends TestCase
         'SupplierAddress::postalCode' => 'Regex {4,5} borne deja la longueur.',
         // Idem cote prestataire (meme Regex CP — M3 Technique).
         'ProviderAddress::postalCode' => 'Regex {4,5} borne deja la longueur.',
+        // Idem cote transporteur (meme Regex CP — M4 Transport).
+        'CarrierAddress::postalCode' => 'Regex {4,5} borne deja la longueur.',
         // Le Choice {PROSPECT,DEPART,RENDU} borne les valeurs (<= 8 < 20).
         'SupplierAddress::addressType' => 'Choice {PROSPECT,DEPART,RENDU} borne deja les valeurs.',
         // Le Choice {QUALIMAT,GMP_PLUS,OVOCOM,COMPTE_PROPRE,AUTRE} borne les valeurs (<= 13 < 20).

tests/Module/Transport/Api/CarrierAddressApiTest.php

@@ -0,0 +1,172 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Transport\Api;
+
+use ApiPlatform\Symfony\Bundle\Test\Client;
+use App\Module\Core\Infrastructure\DataFixtures\RbacDemoFixtures;
+use App\Module\Transport\Domain\Entity\Carrier;
+use App\Module\Transport\Domain\Entity\CarrierAddress;
+use Symfony\Bundle\FrameworkBundle\Console\Application;
+use Symfony\Component\Console\Input\ArrayInput;
+use Symfony\Component\Console\Output\NullOutput;
+
+/**
+ * Sous-ressource Adresse d'un transporteur (spec-back M4 § 4.5, ERP-159).
+ * POST /api/carriers/{id}/addresses, PATCH/DELETE /api/carrier_addresses/{id}.
+ *
+ * Contrat verifie :
+ *  - RG-4.06 : code postal hors ^[0-9]{4,5}$ -> 422 ;
+ *  - RG-4.05 : transporteur affrete + adresse incomplete -> 422 (par champ) ;
+ *  - RG-4.05 : transporteur affrete + adresse complete -> 201 ;
+ *  - PATCH / DELETE OK avec transport.carriers.manage, 403 sans (view seul).
+ *
+ * @internal
+ */
+final class CarrierAddressApiTest extends AbstractCarrierApiTestCase
+{
+    private const string PWD = RbacDemoFixtures::DEMO_PASSWORD;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        // Seed idempotent des roles + matrice § 5.2 + comptes demo (meme chemin
+        // qu'en recette), requis pour les tests de permission (bureau/commerciale).
+        self::bootKernel();
+        $application = new Application(self::$kernel);
+        $application->setAutoExit(false);
+        $exit = $application->run(
+            new ArrayInput([
+                'command'           => 'app:seed-rbac',
+                '--with-demo-users' => true,
+                '--password'        => self::PWD,
+            ]),
+            new NullOutput(),
+        );
+        self::assertSame(0, $exit, 'app:seed-rbac a echoue (permissions transport.carriers.* synchronisees ?).');
+
+        self::ensureKernelShutdown();
+    }
+
+    public function testInvalidPostalCodeReturns422(): void
+    {
+        // Transporteur NON affrete : RG-4.05 ne s'applique pas, seule RG-4.06 joue.
+        $carrier = $this->seedCarrierWithChartered('Cp Invalide', false);
+        $client  = $this->createAdminClient();
+
+        $client->request('POST', '/api/carriers/'.$carrier->getId().'/addresses', [
+            'headers' => ['Content-Type' => self::LD],
+            'json'    => ['postalCode' => '123'], // 3 chiffres -> Regex KO
+        ]);
+        self::assertResponseStatusCodeSame(422);
+    }
+
+    public function testCharteredCarrierIncompleteAddressReturns422(): void
+    {
+        // Transporteur affrete : RG-4.05 exige Pays/CP/Ville/Adresse. CP valide mais
+        // ville + rue manquantes -> 422 conditionnelle (CarrierAddressProcessor).
+        $carrier = $this->seedCarrierWithChartered('Affrete Incomplet', true);
+        $client  = $this->createAdminClient();
+
+        $client->request('POST', '/api/carriers/'.$carrier->getId().'/addresses', [
+            'headers' => ['Content-Type' => self::LD],
+            'json'    => ['postalCode' => '86000'],
+        ]);
+        self::assertResponseStatusCodeSame(422);
+    }
+
+    public function testCharteredCarrierCompleteAddressIsCreated(): void
+    {
+        $carrier = $this->seedCarrierWithChartered('Affrete Complet', true);
+        $client  = $this->createAdminClient();
+
+        $client->request('POST', '/api/carriers/'.$carrier->getId().'/addresses', [
+            'headers' => ['Content-Type' => self::LD],
+            'json'    => [
+                'country'    => 'France',
+                'postalCode' => '86000',
+                'city'       => 'Poitiers',
+                'street'     => '12 rue des Acacias',
+            ],
+        ]);
+        self::assertResponseStatusCodeSame(201);
+    }
+
+    public function testPatchAndDeleteSucceedWithManage(): void
+    {
+        $address = $this->seedAddress('Patch Delete', false);
+        $client  = $this->authenticatedClient('bureau', self::PWD); // manage (matrice § 5.2)
+
+        // PATCH (manage) -> 200
+        $client->request('PATCH', '/api/carrier_addresses/'.$address->getId(), [
+            'headers' => ['Content-Type' => self::MERGE],
+            'json'    => ['city' => 'Lyon'],
+        ]);
+        self::assertResponseStatusCodeSame(200);
+
+        // DELETE (manage) -> 204
+        $client->request('DELETE', '/api/carrier_addresses/'.$address->getId());
+        self::assertResponseStatusCodeSame(204);
+    }
+
+    public function testWriteForbiddenWithoutManage(): void
+    {
+        $address = $this->seedAddress('Forbidden', false);
+        $carrier = $address->getCarrier();
+        self::assertNotNull($carrier);
+        $client = $this->authenticatedClient('commerciale', self::PWD); // view seul
+
+        $client->request('POST', '/api/carriers/'.$carrier->getId().'/addresses', [
+            'headers' => ['Content-Type' => self::LD],
+            'json'    => ['postalCode' => '86000', 'city' => 'Poitiers', 'street' => '1 rue X'],
+        ]);
+        self::assertResponseStatusCodeSame(403);
+
+        $client->request('PATCH', '/api/carrier_addresses/'.$address->getId(), [
+            'headers' => ['Content-Type' => self::MERGE],
+            'json'    => ['city' => 'Lyon'],
+        ]);
+        self::assertResponseStatusCodeSame(403);
+
+        $client->request('DELETE', '/api/carrier_addresses/'.$address->getId());
+        self::assertResponseStatusCodeSame(403);
+    }
+
+    /**
+     * Seede un transporteur minimal en controlant le flag affrete (RG-4.05).
+     */
+    private function seedCarrierWithChartered(string $name, bool $isChartered): Carrier
+    {
+        $em      = $this->getEm();
+        $carrier = new Carrier();
+        $carrier->setName(mb_strtoupper($name, 'UTF-8'));
+        $carrier->setCertificationType('GMP_PLUS');
+        $carrier->setIsChartered($isChartered);
+        $em->persist($carrier);
+        $em->flush();
+
+        return $carrier;
+    }
+
+    /**
+     * Seede un transporteur + une adresse rattachee (pour les tests PATCH/DELETE).
+     */
+    private function seedAddress(string $name, bool $isChartered): CarrierAddress
+    {
+        $em      = $this->getEm();
+        $carrier = $this->seedCarrierWithChartered($name, $isChartered);
+
+        $address = new CarrierAddress();
+        $address->setCarrier($carrier);
+        $address->setPostalCode('86000');
+        $address->setCity('Poitiers');
+        $address->setStreet('12 rue des Acacias');
+        $carrier->addAddress($address);
+        $em->persist($address);
+        $em->flush();
+
+        return $address;
+    }
+}