feat(commercial) : sous-ressources M2 fournisseurs (contacts/adresses/ribs) (ERP-88) (#67)

## ERP-88 — Sous-ressources M2 (contacts / adresses / ribs)

Étape 4/7 du pipeline M2. Dépend de #86 (entités) et #87 (Provider/Processor). Bloque #92.

### Contenu
Opérations API Platform + Processors d'écriture des sous-collections du fournisseur (POST/PATCH/DELETE + GET unitaire).

**SupplierContactProcessor**
- Rattachement au fournisseur parent (404 si absent).
- Normalisation serveur RG-2.12 (Title Case nom/prénom, téléphones chiffres seuls, email lowercase).
- RG-2.04 : firstName **ou** lastName obligatoire (422 sur `firstName`).
- DELETE libre (RG-2.13 front-driven : collection peut rester vide côté back).

**SupplierAddressProcessor**
- Rattachement au fournisseur parent.
- RG-2.05 (CP `^[0-9]{4,5}$`), RG-2.06 (≥1 site), RG-2.09 (type d'adresse) portées par les contraintes d'entité (ERP-86).
- RG-2.10 (catégorie de type FOURNISSEUR) ajoutée via `Assert\Callback validateCategoryType` (propertyPath=`categories`).

**SupplierRibProcessor**
- Rattachement au fournisseur parent.
- RG-2.08 : refus du DELETE du dernier RIB quand `paymentType.code = LCR` → **409**.

### Security différenciée
| Sous-ressource | Écriture | Lecture |
|---|---|---|
| contacts / adresses | `commercial.suppliers.manage` | `commercial.suppliers.view` |
| ribs | `commercial.suppliers.accounting.manage` | `commercial.suppliers.accounting.view` |

POST en `read:false` (parent rattaché manuellement) — parade NonUniqueResult héritée du M1. Messages FR (ERP-107) + `violations[].propertyPath` aligné (ERP-101).

### Vérifications
- `make php-cs-fixer-allow-risky` : 0 fichier à corriger
- `make test` : 483 tests OK
- `debug:router` : 12 routes générées (4 par sous-ressource)

### Hors périmètre (tickets suivants)
- Déclaration RBAC `commercial.suppliers.*` dans `CommercialModule` (#7) — sans elle, l'accès reste 403.
- Tests fonctionnels de la matrice RG (#8) — dépendent du RBAC + fixtures Supplier.

### Notes de review (non bloquantes, alignées M1)
- `position` des sous-collections non exposé à l'API (décision ERP-86, géré serveur).
- M2M `SupplierAddress.contacts` non vérifié same-supplier — comportement identique au M1 (ClientAddress), à traiter globalement si besoin.

---------

Co-authored-by: Matthieu <contact@malio.fr>
Reviewed-on: #67
Co-authored-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
Co-committed-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>

src/Module/Commercial/Domain/Entity/SupplierAddress.php

@@ -4,6 +4,13 @@ declare(strict_types=1);
 
 namespace App\Module\Commercial\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\Commercial\Infrastructure\ApiPlatform\State\Processor\SupplierAddressProcessor;
 use App\Module\Commercial\Infrastructure\Doctrine\DoctrineSupplierAddressRepository;
 use App\Shared\Domain\Attribute\Auditable;
 use App\Shared\Domain\Contract\BlamableInterface;
@@ -17,6 +24,7 @@ use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\Serializer\Attribute\Groups;
 use Symfony\Component\Serializer\Attribute\SerializedName;
 use Symfony\Component\Validator\Constraints as Assert;
+use Symfony\Component\Validator\Context\ExecutionContextInterface;
 
 /**
  * Adresse d'un fournisseur (1:n) — onglet Adresse. Le type d'adresse est un enum
@@ -30,14 +38,60 @@ use Symfony\Component\Validator\Constraints as Assert;
  *    un site obligatoire (RG-2.06, Assert\Count). Site n'a pas de `code`.
  *  - contacts : SupplierContact (meme module).
  *  - categories : CategoryInterface (module Catalog) via resolve_target_entities —
- *    type FOURNISSEUR attendu (RG-2.10, controle au Processor/Validator ERP-89).
+ *    type FOURNISSEUR attendu (RG-2.10, Assert\Callback validateCategoryType).
  *
  * Embarquee sous `supplier.addresses` au detail (groupe supplier:item:read,
- * maillon (a)). Edition via la sous-ressource (POST /api/suppliers/{id}/addresses,
- * PATCH/DELETE /api/supplier_addresses/{id}), branchee a ERP-88.
+ * maillon (a)).
+ *
+ * Sous-ressource API (ERP-88, spec § 4.5) :
+ *  - POST /api/suppliers/{supplierId}/addresses : creation rattachee au
+ *    fournisseur parent (Link toProperty 'supplier'), security
+ *    commercial.suppliers.manage.
+ *  - PATCH / DELETE /api/supplier_addresses/{id} : security
+ *    commercial.suppliers.manage.
+ *  - GET /api/supplier_addresses/{id} : lecture unitaire (security view) — la
+ *    lecture courante reste via le parent. Pas de GET collection autonome.
+ * Tout passe par le SupplierAddressProcessor (rattachement parent). Les regles
+ * RG-2.05/2.06/2.09/2.10 sont portees par les contraintes de l'entite (jouees
+ * avant le processor).
  *
  * Audite (#[Auditable]) + Timestampable / Blamable.
  */
+#[ApiResource(
+    operations: [
+        new Get(
+            security: "is_granted('commercial.suppliers.view')",
+            // site:read + category:read : embarquent les Site / Category lies
+            // (maillon (c)) plutot que des IRI nus dans le retour.
+            normalizationContext: ['groups' => ['supplier:item:read', 'site:read', 'category:read', 'default:read']],
+        ),
+        new Post(
+            uriTemplate: '/suppliers/{supplierId}/addresses',
+            uriVariables: [
+                'supplierId' => new Link(fromClass: Supplier::class, toProperty: 'supplier'),
+            ],
+            // read:false : pas de stade lecture du parent. Le Link toProperty
+            // resoudrait l'enfant (SELECT SupplierAddress ... WHERE supplier = :id)
+            // et casse en NonUniqueResult des >= 2 enfants. Le parent est rattache
+            // manuellement par SupplierAddressProcessor::linkParent (404 si absent).
+            read: false,
+            security: "is_granted('commercial.suppliers.manage')",
+            normalizationContext: ['groups' => ['supplier:item:read', 'site:read', 'category:read', 'default:read']],
+            denormalizationContext: ['groups' => ['supplier:write:addresses']],
+            processor: SupplierAddressProcessor::class,
+        ),
+        new Patch(
+            security: "is_granted('commercial.suppliers.manage')",
+            normalizationContext: ['groups' => ['supplier:item:read', 'site:read', 'category:read', 'default:read']],
+            denormalizationContext: ['groups' => ['supplier:write:addresses']],
+            processor: SupplierAddressProcessor::class,
+        ),
+        new Delete(
+            security: "is_granted('commercial.suppliers.manage')",
+            processor: SupplierAddressProcessor::class,
+        ),
+    ],
+)]
 #[ORM\Entity(repositoryClass: DoctrineSupplierAddressRepository::class)]
 #[ORM\Table(name: 'supplier_address')]
 #[ORM\Index(name: 'idx_supplier_address_supplier', columns: ['supplier_id'])]
@@ -53,6 +107,13 @@ class SupplierAddress implements TimestampableInterface, BlamableInterface
      */
     public const array ADDRESS_TYPES = ['PROSPECT', 'DEPART', 'RENDU'];
 
+    /**
+     * RG-2.10 : seules les categories de ce type sont autorisees sur une adresse
+     * fournisseur. S'appuie sur CategoryInterface::getCategoryTypeCode() (pas
+     * d'import du module Catalog — regle ABSOLUE n°1).
+     */
+    private const string REQUIRED_CATEGORY_TYPE_CODE = 'FOURNISSEUR';
+
     #[ORM\Id]
     #[ORM\GeneratedValue]
     #[ORM\Column]
@@ -154,6 +215,29 @@ class SupplierAddress implements TimestampableInterface, BlamableInterface
         $this->categories = new ArrayCollection();
     }
 
+    /**
+     * RG-2.10 : toute categorie posee sur une adresse fournisseur doit etre de
+     * type FOURNISSEUR -> sinon 422 avec violation sur le champ `categories`
+     * (propertyPath aligne ERP-101, message FR ERP-107). S'appuie sur
+     * CategoryInterface::getCategoryTypeCode() (pas d'import du module Catalog —
+     * regle ABSOLUE n°1). Joue avant la base via la validation API Platform.
+     */
+    #[Assert\Callback]
+    public function validateCategoryType(ExecutionContextInterface $context): void
+    {
+        foreach ($this->categories as $category) {
+            if ($category instanceof CategoryInterface
+                && self::REQUIRED_CATEGORY_TYPE_CODE !== $category->getCategoryTypeCode()) {
+                $context->buildViolation('Type de catégorie non autorisé (FOURNISSEUR attendu).')
+                    ->atPath('categories')
+                    ->addViolation()
+                ;
+
+                return;
+            }
+        }
+    }
+
     public function getId(): ?int
     {
         return $this->id;