[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>

src/Shared/Domain/Contract/BusinessRoleAwareInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Contract;
+
+/**
+ * Expose, sans coupler a la classe concrete User (module Core), le moyen de
+ * savoir si un utilisateur porte un role METIER donne (par son code, cf.
+ * App\Shared\Domain\Security\BusinessRoles).
+ *
+ * Implementee par App\Module\Core\Domain\Entity\User. Permet a un module tiers
+ * (ex: Commercial — RG-1.04, completude Information pour le role Commerciale)
+ * de raisonner sur les roles metier via Security::getUser() sans importer User
+ * (regle ABSOLUE n°1 : pas d'import inter-modules).
+ *
+ * Distinct de UserInterface::getRoles() (roles SYSTEME Symfony ROLE_*, derives
+ * de is_admin) : ici on parle des roles RBAC metier rattaches a l'utilisateur.
+ */
+interface BusinessRoleAwareInterface
+{
+    /**
+     * Vrai si l'utilisateur porte le role RBAC metier identifie par $roleCode
+     * (compare au champ Role::code).
+     */
+    public function hasBusinessRole(string $roleCode): bool;
+}

src/Shared/Domain/Contract/CategoryInterface.php

@@ -19,4 +19,14 @@ interface CategoryInterface
     public function getId(): ?int;
 
     public function getName(): ?string;
+
+    /**
+     * Code du type de categorie rattache (CategoryType::code), ou null si la
+     * categorie n'a pas de type. Expose pour permettre a un module tiers de
+     * raisonner sur le type metier (ex: M1 Commercial — RG-1.03 : un distributor
+     * doit referencer un client categorise DISTRIBUTEUR ; RG-1.29 : categorie
+     * d'adresse limitee a SECTEUR/AUTRE) sans importer la classe concrete
+     * Category (regle ABSOLUE n°1).
+     */
+    public function getCategoryTypeCode(): ?string;
 }

src/Shared/Domain/Security/BusinessRoles.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Security;
+
+/**
+ * Codes des roles METIER MALIO partages entre modules.
+ *
+ * Distincts des roles SYSTEME (cf. App\Module\Core\Domain\Security\SystemRoles :
+ * `admin` / `user`). Un role metier porte une intention fonctionnelle (poste de
+ * travail) et conditionne certaines regles de gestion au-dela des permissions
+ * RBAC pures — ex : RG-1.04 du M1 Clients rend l'onglet Information obligatoire
+ * pour le seul role Commerciale, alors que Commerciale et Bureau partagent les
+ * memes permissions (commercial.clients.view + manage, cf. spec-back M1 § 5.2).
+ *
+ * Ces constantes vivent dans Shared (et non dans un module) pour que :
+ *  - le seed des roles cote Core (ERP-74) reference le meme code sans importer
+ *    une constante du module Commercial (regle ABSOLUE n°1 : pas d'import
+ *    inter-modules) ;
+ *  - le ClientProcessor (module Commercial) detecte le role Commerciale via ce
+ *    meme code, sans dependre de Core.
+ *
+ * Coordination stack M1 :
+ *  - ERP-74 seede le role `commerciale` avec ce code exact.
+ *  - ERP-59 / ERP-60 (declaration RBAC + tests personas) le reutilisent.
+ *  - ERP-55 (ici) ne fait que le REFERENCER : tant qu'aucun user ne porte le
+ *    role `commerciale`, la validation de completude Information reste dormante.
+ */
+final class BusinessRoles
+{
+    /**
+     * Role metier « Commerciale » — code de Role RBAC (champ Role::code,
+     * snake_case impose par la regex Role). Conditionne RG-1.04.
+     */
+    public const string COMMERCIALE = 'commerciale';
+
+    private function __construct()
+    {
+        // Classe de constantes : non instanciable.
+    }
+}