feat(commercial) : validation back de la relation + suivi de revue MR (ERP-119)

- validation serveur « relation choisie => FK obligatoire » : champ transitoire
  relationType (non persiste) + Assert\Callback portant la 422 sur distributor /
  broker, que le back ne pouvait pas deriver des seules FK nullable
- mutualisation des payloads d'ecriture clients : new.vue consomme buildMainPayload
  / buildAddressPayload / buildRibPayload (fin de la duplication create/edit)
- COMMENT ON TABLE client_address : ajout des types Courtier / Distributeur
  (catalogue + migration Version20260609120000)
- tests : violationsByPath remonte dans AbstractCommercialApiTestCase (fin des
  copies inline) + couverture de la nouvelle RG relation

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

@@ -25,6 +25,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;
 
 /**
  * Client (M1 Commercial) — entite racine du repertoire clients. Porte le
@@ -171,6 +172,17 @@ class Client implements TimestampableInterface, BlamableInterface
     #[Groups(['client:read', 'client:write:main'])]
     private bool $triageService = false;
 
+    // Champ transitoire (NON persiste : aucune colonne ORM) portant l'intention UI
+    // « ce client depend d'un distributeur / courtier ». Write-only (groupe
+    // d'ecriture main uniquement, pas de groupe de lecture -> jamais serialise en
+    // sortie). Sert exclusivement a la validation croisee validateRelationName :
+    // si une relation est choisie, la FK correspondante (distributor / broker)
+    // devient obligatoire. Non mappe ORM -> non audite, et toujours null une fois
+    // l'entite rechargee depuis la base (ne sert qu'au cycle d'une ecriture).
+    #[Assert\Choice(choices: ['distributeur', 'courtier'], message: 'Le type de relation est invalide.')]
+    #[Groups(['client:write:main'])]
+    private ?string $relationType = null;
+
     // RG : au moins une categorie (Count min 1). M2M vers Category via le contrat
     // CategoryInterface (resolve_target_entities -> Category).
     /** @var Collection<int, CategoryInterface> */
@@ -333,6 +345,45 @@ class Client implements TimestampableInterface, BlamableInterface
         return $this;
     }
 
+    public function getRelationType(): ?string
+    {
+        return $this->relationType;
+    }
+
+    public function setRelationType(?string $relationType): static
+    {
+        $this->relationType = $relationType;
+
+        return $this;
+    }
+
+    /**
+     * RG-1.03 bis : si l'utilisateur declare une relation (« depend d'un
+     * distributeur / courtier » via le champ transitoire relationType), la FK
+     * correspondante est obligatoire. Le back ne peut pas deviner cette intention
+     * a partir des seules FK nullable (distributor=null ne distingue pas « pas de
+     * relation » de « relation choisie sans nom »), d'ou relationType qui la porte.
+     * Violation portee sur distributor / broker (champ fautif cote formulaire), de
+     * sorte que useFormErrors la mappe inline sous le bon select (ERP-101).
+     */
+    #[Assert\Callback]
+    public function validateRelationName(ExecutionContextInterface $context): void
+    {
+        if ('distributeur' === $this->relationType && null === $this->distributor) {
+            $context->buildViolation('Le nom du distributeur est obligatoire.')
+                ->atPath('distributor')
+                ->addViolation()
+            ;
+        }
+
+        if ('courtier' === $this->relationType && null === $this->broker) {
+            $context->buildViolation('Le nom du courtier est obligatoire.')
+                ->atPath('broker')
+                ->addViolation()
+            ;
+        }
+    }
+
     public function isTriageService(): bool
     {
         return $this->triageService;

src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php

@@ -219,7 +219,7 @@ final class ColumnCommentsCatalog
             ] + self::timestampableBlamableComments(),
 
             'client_address' => [
-                '_table'                  => 'Adresses d un client (1:n) — prospect exclusif de livraison/facturation (RG-1.06/07/08), >= 1 site rattache (RG-1.10).',
+                '_table'                  => 'Adresses d un client (1:n) — types prospect / livraison / facturation (exclusivites RG-1.06/07/08) + Courtier / Distributeur autonomes (exclusifs de tout autre usage), >= 1 site rattache (RG-1.10).',
                 'id'                      => 'Identifiant interne auto-incremente.',
                 'client_id'               => 'FK -> client.id, ON DELETE CASCADE — client proprietaire de l adresse.',
                 'is_prospect'             => 'Adresse de prospection — exclusive de is_delivery/is_billing (RG-1.06/07/08, chk_client_address_prospect_exclusive). Faux par defaut.',