feat(commercial) : migrate M1 client tables + accounting referentials + extend category_type seed

## Contexte

Spécifications front + back du **Module 1 — Répertoire clients** (premier module métier Tiers, extension du module `Commercial` existant).

Origine : V0 client `.docx` du 22/05/2026 (`M1-reportoire-clients.docx`) + maquette Figma `https://www.figma.com/design/jRYgT0T9c03VsEbjGhCwwS/Composants---Design-System?node-id=1132-31898`.

Pattern de rédaction : strictement aligné sur `docs/specs/M0-categories/` (spec-front léger + spec-back très détaillé).

## Contenu

- `docs/specs/M1-clients/spec-front.md` (289 lignes) — V0 client, structure UI, composants Malio, permissions par rôle, règles de formatage
- `docs/specs/M1-clients/spec-back.md` (1056 lignes) — décisions archi, modèle données, migration SQL Postgres, API REST, RBAC matrice complète, 27 RG numérotées, tests à automatiser, 16 HP, liens & dépendances

## Décisions structurantes (validées avec Tristan le 28/05/2026)

- **Module** : extension de `Commercial/` (pas nouveau module)
- **Catégories Client** : M2M `client_category` + seed `CategoryType` (`DISTRIBUTEUR`, `COURTIER`, `SECTEUR`, `AUTRE`)
- **Distributeur / Courtier** : 2 FK auto-référentes nullables sur `client` + contrainte CHECK mutex
- **Workflow création** : sauvegarde incrémentale par onglet (POST formulaire principal → PATCH par onglet)
- **Onglets « À venir »** (Transport / Statistiques / Rapports / Échanges) : placeholders blancs (frames vides, pas de message texte)
- **Archive vs delete** : flag `is_archived` exposé au M1, colonne `deleted_at` préparée mais non exposée (HP M2)
- **API adresse** : api-adresse.data.gouv.fr (BAN), appel direct front via `useAddressAutocomplete()`
- **Unicité métier** : SIREN + `companyName` + email (indexes partiels Postgres, ignorent archivés et soft-deletés)
- **Téléphones** : 2 colonnes plates `phone_primary` + `phone_secondary`
- **Export** : XLSX uniquement (controller custom avec `priority: 1`)
- **Compta = lecture seule** ⚠ s'écarte du tableau du `.docx` (ligne « Compta = Ajout/Modification Comptabilité uniquement » invalidée) — documenté en HP-M2-10

## Seed M1 (référentiels comptables)

| Référentiel | Valeurs |
|---|---|
| `tva_mode` | `FRANCE_VENTES`, `EXPORT_VENTES`, `INTRACOM_VENTES` |
| `payment_delay` | `J15`, `J30`, `A_RECEPTION` |
| `payment_type` | `VIREMENT`, `LCR`, `NON_SOUMISE`, `CHEQUE` |
| `bank` | `SG`, `CIC`, `CA` (Société Générale / CIC / Crédit Agricole) |
| `category_type` (extension M0) | `DISTRIBUTEUR`, `COURTIER`, `SECTEUR`, `AUTRE` |

## RG ajoutées au-delà du `.docx`

- **RG-1.14** : ≥ 1 bloc Contact valide obligatoire (renforcement Tristan)
- **RG-1.15/16/17** : unicités SIREN / nom / email
- **RG-1.18** : `companyName` UPPERCASE serveur
- **RG-1.19** : `firstName` / `lastName` Capitalize serveur
- **RG-1.20** : téléphones chiffres seuls en BDD, formatage `XX XX XX XX XX` au front
- **RG-1.21** : emails lowercase serveur
- **RG-1.22/23** : archivage / restauration + conflit unicité à la restauration

## Permissions RBAC (à synchroniser dans les 3 miroirs au moment du dev)

| Permission | Admin | Bureau | Compta | Commerciale | Usine |
|---|---|---|---|---|---|
| `commercial.clients.view` | ✅ | ✅ | ✅ | ✅ | ❌ |
| `commercial.clients.manage` | ✅ | ✅ | ❌ | ✅ | ❌ |
| `commercial.clients.accounting.view` | ✅ | ❌ | ✅ | ❌ | ❌ |
| `commercial.clients.accounting.manage` | ✅ | ❌ | ❌ | ❌ | ❌ |
| `commercial.clients.archive` | ✅ | ❌ | ❌ | ❌ | ❌ |

## Prochaines étapes (hors MR)

1. Revue / validation des specs par Matthieu
2. Création du **TaskGroup Lesstime** `M1 — Répertoire clients` (projet `ERP / Starseed`, projectId=6)
3. Découpage en ~14 tickets (ordre indicatif listé en bas du `spec-back.md`)

## Reviewer suggéré

Matthieu (CP MALIO).

## Cible

`develop`.

---------

Co-authored-by: admin malio <malio@yuno.malio.fr>
Co-authored-by: Matthieu <mtholot19@gmail.com>
Reviewed-on: #23
Co-authored-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
Co-committed-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>

config/version.yaml

@@ -1,2 +1,2 @@
 parameters:
-    app.version: '0.1.53'
+    app.version: '0.1.54'

docs/specs/M1-clients/spec-front.md

@@ -0,0 +1,289 @@
+---
+# === IDENTITÉ ===
+module: M1
+nom: "Répertoire clients"
+ecran: repertoire-clients
+owner_spec: Matthieu
+backup_spec: Tristan
+version: V0
+date_redaction: 2026-05-28
+
+# === LIENS ===
+maquette_figma: "https://www.figma.com/design/jRYgT0T9c03VsEbjGhCwwS/Composants---Design-System?node-id=1132-31898"
+regles_metier: [RG-1.01, RG-1.02, RG-1.03, RG-1.04, RG-1.05, RG-1.06, RG-1.07, RG-1.08, RG-1.09, RG-1.10, RG-1.11, RG-1.12, RG-1.13, RG-1.14, RG-1.15, RG-1.16, RG-1.17, RG-1.18, RG-1.19, RG-1.20, RG-1.21, RG-1.22, RG-1.23, RG-1.24, RG-1.25, RG-1.26, RG-1.27, RG-1.28, RG-1.29]
+roles: [Admin, Bureau, Compta, Commerciale, Usine]
+lien_spec_back: ./spec-back.md
+
+# === VALIDATION CLIENT #1 ===
+client_validation_1:
+  statut: validee
+  date: 2026-05-22
+  canal: ecrit
+  valide_par: "Matthieu (CP MALIO) — validation implicite, périmètre projet"
+  resume: "Module 1 — Répertoire clients. Page d'entrée Commercial. Datatable + 3 écrans (Ajouter / Consulter / Modifier). Création par onglets : Information / Contact / Adresse / Comptabilité (Transport, Statistiques, Rapports, Échanges = placeholders blancs)."
+  trace_archivee: "uploads/4a1b026f-M1-reportoire-clients.docx (V0 d'origine .docx)"
+
+# === LIEN LESSTIME ===
+lesstime_taskgroup_id: 23
+lesstime_project_id: 6
+statut_global: en_dev
+---
+
+# Module 1 — Répertoire clients (V0 front)
+
+> **Origine** : spec front V0 livrée le 22/05/2026 (`M1-reportoire-clients.docx`). Restitution Markdown pour intégration au workflow MALIO. Le contenu original n'est pas modifié — toute précision et toute décision (en particulier côté back) vit dans [`spec-back.md`](./spec-back.md).
+
+## But
+
+Permettre aux utilisateurs Starseed (selon rôle) de gérer le **répertoire des clients** de l'organisation : consultation, création, modification, archivage. Cette page est la **porte d'entrée du module Commercial**.
+
+## Accès
+
+- **Depuis** : menu principal → section **Commercial** → entrée « Répertoire clients »
+- **Rôles autorisés** :
+
+| Rôle | Consultation | Création / Modification | Archivage |
+|---|---|---|---|
+| **Admin** | ✅ Tout | ✅ Tout | ✅ |
+| **Bureau** | ✅ Tout | ✅ Tout sauf onglet Comptabilité | ❌ |
+| **Compta** | ✅ Tout | ✅ Onglet Comptabilité uniquement | ❌ |
+| **Commerciale** | ✅ Tout sauf Comptabilité | ✅ Tout sauf Comptabilité | ❌ |
+| **Usine** | ❌ | ❌ | ❌ |
+
+> **Note** : aligné sur le docx d'origine — Compta édite uniquement l'onglet Comptabilité (champs SIREN / TVA / Délai de règlement / Type de règlement / Banque / RIBs). Compta ne peut pas **créer** un client (pas de droit `manage` général), mais peut éditer la partie comptable d'un client existant créé par Admin ou Bureau.
+
+## Navigation
+
+L'écran est la page d'entrée du module **Commercial**. Titre : « **Répertoire clients** ».
+
+- Affichage principal : un **datatable** listant tous les clients **actifs** de l'organisation (les clients archivés sont masqués par défaut — filtre UI dédié pour les voir).
+- **Clic sur une ligne** → bascule sur l'écran **Consultation client** (page dédiée, pas un drawer — cf. maquette Figma).
+- **Bouton « + Ajouter »** (en haut à droite) → bascule sur l'écran **Ajouter un client**.
+- **Bouton « Exporter »** (en haut à droite) → télécharge un **fichier XLSX** des clients **affichés** (cf. filtre actif). Format détaillé dans [`spec-back.md` § Export](./spec-back.md).
+
+## Datatable du Répertoire
+
+Composant : `<MalioDataTable>`. Colonnes (à raffiner avec Tristan en revue maquette) :
+
+| Colonne | Source | Tri |
+|---|---|---|
+| **Nom entreprise** | `client.companyName` | ASC par défaut |
+| **Contact principal** | `firstName + lastName` | Oui |
+| **Téléphone principal** | `phonePrimary` (formaté `XX XX XX XX XX`) | Non |
+| **Email principal** | `email` | Oui |
+| **Catégories** | liste des codes catégories séparés par `,` | Non |
+| **Site(s)** | sites rattachés à au moins une adresse (badges colorés) | Non |
+
+> **Filtre archivés** : toggle UI en haut du datatable. Désactivé par défaut. État local (pas dans l'URL — cf. règle ABSOLUE Starseed n°6).
+
+> **Pagination** : front via `<MalioDataTable>` (volumétrie cible faible — quelques centaines). Tri serveur `companyName ASC` par défaut.
+
+## Écran « Ajouter un client »
+
+Création par **onglets successifs avec validation incrémentale** : pour pouvoir passer à l'onglet suivant, il faut avoir validé l'onglet en cours. **Une fois un onglet validé, on passe automatiquement au suivant**, et les champs de l'onglet validé passent en lecture seule + bouton « Valider » désactivé (disabled).
+
+### Formulaire principal (pré-onglets)
+
+C'est le 1er bloc à remplir. Sans validation de ce formulaire, les onglets ne sont pas accessibles.
+
+| Champ | Type composant | Obligatoire | Règle |
+|---|---|---|---|
+| **Nom du client (Entreprise)** | `<MalioInputText>` | Oui | RG-1.18 (normalisation UPPERCASE serveur) |
+| **Nom du contact principal** | `<MalioInputText>` | Conditionnel | RG-1.01 + RG-1.19 (Capitalize) |
+| **Prénom du contact principal** | `<MalioInputText>` | Conditionnel | RG-1.01 + RG-1.19 (Capitalize) |
+| **Catégorie** | `<MalioSelectCheckbox>` (multi) | Oui | Liste des `Category` de l'API ; M2M Client ↔ Category |
+| **Téléphone principal** | `<MalioInputText>` (masque tel) | Oui | RG-1.02 + RG-1.20 (format `XX XX XX XX XX`) |
+| **Téléphone secondaire** | `<MalioInputText>` (masque tel) | Non | Apparaît au clic sur le bouton `+` (RG-1.02). Max 2 — bouton `+` disparaît une fois rempli. |
+| **Email** | `<MalioInputText>` type email | Oui | RG-1.21 (lowercase) |
+| **Distributeur / Courtier** | `<MalioSelect>` | Non | Valeurs : `Dépend du distributeur` / `Dépend du courtier` / `Aucun`. RG-1.03 conditionne les 2 champs suivants. |
+| **Nom du distributeur** | `<MalioSelect>` | Conditionnel | Visible si « Dépend du distributeur ». Liste = clients ayant ≥ 1 catégorie de type `DISTRIBUTEUR`. RG-1.03. |
+| **Nom du courtier** | `<MalioSelect>` | Conditionnel | Visible si « Dépend du courtier ». Liste = clients ayant ≥ 1 catégorie de type `COURTIER`. RG-1.03. |
+| **Prestation de triage** | `<MalioCheckbox>` | Non | — |
+
+**Action** : « Valider » (`<MalioButton>`) → POST `/api/clients` ([`spec-back.md` § 4.3](./spec-back.md)). Si succès, on passe automatiquement à l'onglet « Information ».
+
+### Onglet « Information »
+
+Saisir les informations de l'entreprise.
+
+| Champ | Type | Obligatoire | Règle |
+|---|---|---|---|
+| **Description** | `<MalioInputTextArea>` | Conditionnel | RG-1.04 (obligatoire pour rôle Commerciale) |
+| **Concurrents** | `<MalioInputText>` | Conditionnel | RG-1.04 |
+| **Date de création** (de l'entreprise) | `<input type="date">` (exception Malio — pas de composant date couvert) | Conditionnel | RG-1.04 |
+| **Nombre de salariés** | `<MalioInputNumber>` | Conditionnel | RG-1.04 |
+| **CA €** | `<MalioInputAmount>` | Conditionnel | RG-1.04 |
+| **Dirigeant** | `<MalioInputText>` | Conditionnel | RG-1.04 |
+| **Résultat €** | `<MalioInputAmount>` | Conditionnel | RG-1.04 |
+
+**Action** : « Valider » → PATCH partiel `/api/clients/{id}` (groupe `client:write:information`).
+
+### Onglet « Contact »
+
+Saisir un ou plusieurs contacts associés au client. Le 1er bloc est **pré-rempli** depuis les champs du formulaire principal (Nom, Prénom, Téléphone, Email — édition autorisée).
+
+**Bloc Contact** :
+
+| Champ | Type | Obligatoire | Règle |
+|---|---|---|---|
+| **Nom** | `<MalioInputText>` | Conditionnel | RG-1.05 + RG-1.19 (Capitalize) |
+| **Prénom** | `<MalioInputText>` | Conditionnel | RG-1.05 + RG-1.19 (Capitalize) |
+| **Fonction** | `<MalioInputText>` | Non | — |
+| **Téléphone** (x1, +1 possible) | `<MalioInputText>` | Non | RG-1.20 (format) |
+| **Email** | `<MalioInputText>` type email | Non | RG-1.21 (lowercase) |
+
+**RG-1.14 (renforcement validée par Tristan le 28/05)** : **au moins 1 bloc Contact valide** (au moins Nom OU Prénom rempli) est obligatoire pour valider l'onglet. Donc l'onglet Contact ne peut pas être finalisé vide.
+
+**Actions** :
+- « + Nouveau contact » : ajoute un bloc. Bouton **désactivé tant que le bloc précédent n'a pas Prénom OU Nom rempli** (RG-1.05).
+- « Supprimer » (icône) sur un bloc : modal de confirmation (`<MalioButton>` Annuler / Confirmer). Si Oui → suppression du bloc.
+- « Valider » → PATCH `/api/clients/{id}/contacts` (création/mise à jour de la collection).
+
+### Onglet « Adresse »
+
+Saisir une ou plusieurs adresses du client, rattachées à un ou plusieurs sites Starseed (Châtellerault 86 / Saint-Jean 17 / Pommevic 82) et à des contacts.
+
+**Bloc Adresse** :
+
+| Champ | Type | Obligatoire | Règle |
+|---|---|---|---|
+| **Prospect** | `<MalioCheckbox>` | Non | RG-1.06 — masque Adresse de livraison + Facturation si coché |
+| **Adresse de livraison** | `<MalioCheckbox>` | Non | RG-1.07 — masque Prospect si coché |
+| **Facturation** | `<MalioCheckbox>` | Non | RG-1.08 — masque Prospect si coché ; affiche le champ Email (RG-1.11) |
+| **Catégorie** | `<MalioSelectCheckbox>` (multi) | Oui | Liste des `Category` de **type SECTEUR + AUTRE** uniquement (cf. décision Q5 — DISTRIBUTEUR et COURTIER qualifient une relation entre clients, pas un lieu) |
+| **Pays** | `<MalioSelect>` | Oui | Préremplie « France » |
+| **Code postal** | `<MalioInputText>` (masque numérique) | Oui | RG-1.09 — déclenche autocomplete ville via BAN |
+| **Ville** | `<MalioSelect>` | Oui | RG-1.09 — alimentée par api-adresse.data.gouv.fr suivant le CP |
+| **Adresse** | `<MalioInputText>` (saisie assistée) | Oui | RG-1.09 — autocomplete BAN |
+| **Adresse complémentaire** | `<MalioInputText>` | Non | — |
+| **Sites Starseed** | `<MalioSelectCheckbox>` (multi-checkbox 86 / 17 / 82) | Oui | RG-1.10 — ≥ 1 site obligatoire |
+| **Contact(s) rattaché(s)** | `<MalioSelectCheckbox>` (multi) | Non | Liste = blocs Contact saisis dans l'onglet Contact |
+| **Email (facturation)** | `<MalioInputText>` type email | Conditionnel | RG-1.11 — visible/obligatoire uniquement si « Facturation » coché |
+
+**Actions** :
+- « + Nouvelle Adresse » : ajoute un bloc identique.
+- « Supprimer » : modal de confirmation puis suppression.
+- « Valider » → PATCH `/api/clients/{id}/addresses`.
+
+### Onglet « Transport »
+
+🚧 **Placeholder blanc au M1.** Frame vide. Aucun champ. Aucun bouton de validation. L'utilisateur passe automatiquement à l'onglet suivant. **Pas de mention « En cours »** — c'est juste blanc (décision Tristan 28/05).
+
+### Onglet « Comptabilité »
+
+⚠ **Accessible aux rôles avec `commercial.clients.accounting.manage`** (Admin + Compta au M1). Bureau et Commerciale ne voient pas l'onglet. **Compta peut éditer cet onglet** (champs SIREN / N° compte / TVA / Délai / Type de règlement / Banque / RIBs) — cf. décision Q1, aligné docx. Compta ne peut pas créer un client (pas de `manage` général).
+
+**Champs comptables** :
+
+| Champ | Type | Obligatoire | Règle |
+|---|---|---|---|
+| **SIREN** | `<MalioInputText>` (masque 9 chiffres) | Oui | Format 9 chiffres. **Pas d'unicité** (décision Q4) |
+| **Numéro de compte** | `<MalioInputText>` | Oui | — |
+| **Mode de TVA** | `<MalioSelect>` | Oui | Liste depuis `/api/tva_modes` |
+| **N° de TVA** | `<MalioInputText>` | Oui | — |
+| **Délai de règlement** | `<MalioSelect>` | Oui | Liste depuis `/api/payment_delays` |
+| **Type de règlement** | `<MalioSelect>` | Oui | Liste depuis `/api/payment_types` |
+| **Banque** | `<MalioSelect>` | Conditionnel | RG-1.12 — visible et obligatoire **si** Type de règlement = `VIREMENT`. Liste depuis `/api/banks`. |
+
+**Bloc RIB** (0..n blocs, présence obligatoire conditionnée par RG-1.13) :
+
+| Champ | Type | Obligatoire | Règle |
+|---|---|---|---|
+| **Libellé** | `<MalioInputText>` | Oui (si LCR) | RG-1.13 |
+| **BIC** | `<MalioInputText>` | Oui (si LCR) | RG-1.13 — `#[AuditIgnore]` (champ sensible) |
+| **IBAN** | `<MalioInputText>` | Oui (si LCR) | RG-1.13 — `#[AuditIgnore]` (champ sensible) |
+
+**Actions** :
+- « + RIB » : ajoute un bloc.
+- « Supprimer » (icône) : modal de confirmation.
+- « Valider » → PATCH `/api/clients/{id}/accounting`.
+
+### Onglets « Statistiques » / « Rapports » / « Échanges »
+
+🚧 **Placeholders blancs au M1.** Mêmes règles que Transport (frames vides, pas de validation).
+
+## Écran « Consultation client »
+
+Tous les champs en **lecture seule**. Layout identique à l'écran Ajouter mais sans bouton « Valider », sans bouton `+` pour ajouter des blocs Contact / Adresse / RIB.
+
+- **Flèche retour** (à gauche) → revient au Répertoire.
+- **Bouton « Modifier »** (à droite, visible si l'utilisateur a la permission `commercial.clients.manage`) → bascule sur l'écran Modification.
+- **Bouton « Archiver »** (à droite, visible **uniquement pour Admin** via permission `commercial.clients.archive`) → ouvre une modal de confirmation, puis PATCH `/api/clients/{id}` `{ "isArchived": true }`. Le client passe en archivé (cf. flag `is_archived`).
+
+> Le client archivé peut être restauré (`isArchived: false`) — bouton « Restaurer » remplace « Archiver » dans la consultation d'un archivé. Décision validée Tristan 28/05.
+
+### Onglets affichés en consultation
+
+Mêmes onglets qu'en création, **plus** les 4 placeholders blancs. L'utilisateur navigue librement entre les onglets (pas de séquence forcée en consultation).
+
+## Écran « Modification client »
+
+Comportement identique à l'écran Ajouter sauf :
+- **Pas de formulaire principal** (les champs principaux sont édités via les onglets correspondants).
+- Les champs sont **pré-remplis** avec les valeurs actuelles.
+- **Validation par onglet** : on peut modifier UN onglet sans toucher aux autres (PATCH partiel).
+- Les onglets pour lesquels l'utilisateur n'a **pas** la permission `manage` restent en lecture seule (pas de bouton Valider, pas d'icône suppression de bloc).
+- Les onglets placeholders restent inaccessibles à l'édition (blancs).
+
+## Composants UI à utiliser (`@malio/layer-ui`)
+
+- **Datatable** : `<MalioDataTable>` (Répertoire)
+- **Input texte** : `<MalioInputText>`
+- **Input numérique** : `<MalioInputNumber>`
+- **Input montant** : `<MalioInputAmount>` (CA, Résultat)
+- **TextArea** : `<MalioInputTextArea>` (Description)
+- **Select simple** : `<MalioSelect>` (Pays, Ville, distributeur/courtier, refs comptables)
+- **Select multi (cases à cocher)** : `<MalioSelectCheckbox>` (Catégorie, Sites, Contacts rattachés)
+- **Checkbox** : `<MalioCheckbox>` (Prospect, Adresse livraison, Facturation, Prestation de triage)
+- **Bouton** : `<MalioButton>`, `<MalioButtonIcon>`
+- **Toasts** : standards via `useApi()`
+
+**Exceptions autorisées** (à commenter `// TODO migrer quand Malio couvre`) :
+- `<input type="date">` pour « Date de création » (composant `MalioDate` non couvert)
+- Modal de confirmation : composant à confirmer côté équipe front (probablement `<MalioModal>` ou un wrapper à créer dans `frontend/shared/`)
+
+## Règles de formatage et normalisation
+
+Le serveur normalise systématiquement (cf. RG-1.18 à RG-1.21 dans [`spec-back.md`](./spec-back.md)) :
+
+| Champ | Normalisation serveur | Affichage front |
+|---|---|---|
+| Nom entreprise (`companyName`) | UPPERCASE intégral | UPPERCASE |
+| Nom + Prénom contact | Capitalize (1ère lettre majuscule + reste minuscule) | identique |
+| Téléphone (`phonePrimary`, `phoneSecondary`, contact phones) | Chiffres uniquement en BDD | Formaté `XX XX XX XX XX` à l'affichage (filter Vue) |
+| Email | lowercase intégral | identique |
+
+> **Le front ne fait pas la normalisation** — il envoie la valeur saisie, le serveur normalise puis renvoie la valeur normalisée. L'UI affiche immédiatement la valeur normalisée renvoyée par l'API. Cohérent avec le pattern `useApi()`.
+
+## API adresse postale
+
+Le composant `Code postal` + `Ville` + `Adresse` est branché sur **api-adresse.data.gouv.fr** (Base Adresse Nationale, gratuite, française).
+
+- Composable dédié `useAddressAutocomplete()` (à créer en M1).
+- Appel HTTP **direct depuis le front** (CORS OK), pas de proxy back.
+- Pattern : à la saisie du code postal (5 chiffres), GET `https://api-adresse.data.gouv.fr/search/?q={cp}&type=municipality` → alimente le select Ville. Sur saisie d'adresse : `?q={addr}&postcode={cp}&type=housenumber` → suggestions adresse.
+- Cas dégradé : si l'API ne répond pas (offline, timeout), le champ Ville devient un `<MalioInputText>` libre éditable + toast d'avertissement. Validation serveur acceptera la saisie libre.
+
+## Points laissés ouverts par la V0 (résolus côté back)
+
+| # | Zone d'ombre V0 | Résolution (cf. `spec-back.md`) |
+|---|---|---|
+| 1 | Catégorie en multi-select non clarifiée (1 ou n par client) | **M2M `client_category`** validée. CategoryType seedé avec `DISTRIBUTEUR`, `COURTIER`, `SECTEUR`, `AUTRE` (HP-3 du M0 levé). |
+| 2 | Distributeur / Courtier : liste de quoi ? | **Auto-référence Client** via 2 FK nullables `distributor_id` et `broker_id` (cf. RG-1.03). Une seule des deux est remplie à la fois. |
+| 3 | Onglet « Comptabilité » : qui édite ? | **Admin et Compta** peuvent éditer l'onglet Comptabilité (`commercial.clients.accounting.manage`). Bureau / Commerciale ne voient pas l'onglet. Compta ne peut pas créer un client (pas de `manage` global), mais peut éditer la partie comptable d'un client existant. |
+| 4 | Workflow par onglet | **Sauvegarde incrémentale**. POST formulaire principal crée le `Client` (status implicite « actif »). Chaque onglet validé = PATCH partiel par groupe de sérialisation dédié. Pas d'état « draft ». |
+| 5 | Onglets « À venir » | **Placeholders blancs** (frames vides, pas de message). Ré-activables sans rebuild quand les modules associés arriveront. |
+| 6 | Archive vs soft delete | **Flag `is_archived` séparé de `deleted_at`**. Archive ≠ delete : un client archivé est masqué par défaut mais reste en BDD éditable (Admin seul). Filtres UI distincts. Soft delete = HP M2. |
+| 7 | Unicité métier | **Nom d'entreprise uniquement** (case-insensitive, parmi non-archivés) — décision Q4. SIREN et email NON uniques. Index partiel Postgres `uq_client_company_name_active`. Doublon de nom → 409 Conflict. |
+| 8 | Téléphones (max 2) | **2 colonnes plates** `phone_primary` + `phone_secondary`. Pas de table séparée. |
+| 9 | API code postal | **api-adresse.data.gouv.fr** (BAN). Appel direct front via composable dédié. Cas dégradé : saisie libre + toast. |
+| 10 | Référentiels comptables | **4 entités CRUD-ables** (`TvaMode`, `PaymentDelay`, `PaymentType`, `Bank`) seedées au M1, CRUD admin futur (HP-M2). |
+| 11 | Format de l'export | **XLSX uniquement** au M1. CSV à étudier en HP. |
+
+---
+
+## 📦 Tickets Lesstime générés
+
+**TaskGroup Lesstime** : à créer — `M1 — Répertoire clients` (projet `ERP / Starseed`, projectId=6).
+
+> Détail complet, table des tickets et action manuelle dans Lesstime → voir [`spec-back.md § Tickets Lesstime générés`](./spec-back.md#-tickets-lesstime-générés).

migrations/Version20260601000000.php

@@ -0,0 +1,538 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DoctrineMigrations;
+
+use App\Shared\Infrastructure\Database\ColumnCommentsCatalog;
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+/**
+ * M1 — Repertoire clients (ERP-53) : creation de toute la structure BDD du
+ * module Commercial (clients + sous-collections + referentiels comptables).
+ *
+ * Tables creees :
+ *  - Referentiels comptables (statiques, seedes ici) : tva_mode, payment_delay,
+ *    payment_type, bank.
+ *  - Table principale : client (formulaire + Information + Comptabilite +
+ *    archive + soft-delete + Timestampable/Blamable).
+ *  - Sous-collections : client_category (M2M), client_contact (1:n),
+ *    client_address (1:n), client_rib (1:n).
+ *  - Jointures de client_address : client_address_site, client_address_contact,
+ *    client_address_category.
+ *
+ * Seed `category_type` (extension M0) : DISTRIBUTEUR / COURTIER / SECTEUR /
+ * AUTRE, en `ON CONFLICT (code) DO NOTHING` (idempotent — la table peut deja
+ * porter des donnees en prod). En dev/test, les fixtures purgent et re-seedent
+ * ces 4 types (cf. CategoryTypeFixtures) ; ce seed migration couvre la prod ou
+ * les fixtures ne tournent pas.
+ *
+ * Namespace racine `DoctrineMigrations` (regle ABSOLUE Starseed n°11) et NON
+ * `App\Module\Commercial\...` : avec plusieurs migrations_paths, Doctrine
+ * Migrations 3.x trie par FQCN alphabetique (AlphabeticalComparator → strcmp).
+ * Un namespace `App\Module\Commercial\...` trierait AVANT `DoctrineMigrations\...`
+ * et la migration s'executerait avant la creation de user/category/site sur
+ * base vide → echec des FK. Le namespace racine garantit l'ordre par timestamp.
+ *
+ * Style DDL aligne sur la migration M0 (Version20260527164000) plutot que sur
+ * le pseudo-SQL de la spec § 3.2 : `INT GENERATED BY DEFAULT AS IDENTITY` (et
+ * non SERIAL), `TIMESTAMP(0) WITHOUT TIME ZONE` (et non TIMESTAMPTZ, car le
+ * `TimestampableBlamableTrait` mappe `datetime_immutable`). Garantit que
+ * `schema:update` restera un no-op quand les entites arriveront (ticket ERP-54).
+ *
+ * Decision Q4 (29/05/2026) : unicite metier sur le NOM DE SOCIETE uniquement.
+ * Pas d'index unique sur siren ni email (RG-1.15 / RG-1.17 supprimees).
+ *
+ * Chaque colonne porte un `COMMENT ON COLUMN` (regle ABSOLUE n°12, garde-fou
+ * ColumnsHaveSqlCommentTest). Les tables n'etant pas encore mappees par l'ORM,
+ * ces commentaires survivent au `schema:update --force` du setup de test.
+ */
+final class Version20260601000000 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'ERP-53 (M1) : tables client + sous-collections + referentiels comptables + seed category_type.';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $this->createAccountingReferentials();
+        $this->createClientTable();
+        $this->createClientCategory();
+        $this->createClientContact();
+        $this->createClientAddress();
+        $this->createClientAddressJoinTables();
+        $this->createClientRib();
+        $this->seedCategoryTypes();
+    }
+
+    public function down(Schema $schema): void
+    {
+        // Ordre inverse des dependances FK : on supprime d'abord les jointures
+        // et sous-collections, puis client, puis les referentiels.
+        $this->addSql('DROP TABLE client_address_category');
+        $this->addSql('DROP TABLE client_address_contact');
+        $this->addSql('DROP TABLE client_address_site');
+        $this->addSql('DROP TABLE client_rib');
+        $this->addSql('DROP TABLE client_address');
+        $this->addSql('DROP TABLE client_contact');
+        $this->addSql('DROP TABLE client_category');
+        $this->addSql('DROP TABLE client');
+        $this->addSql('DROP TABLE bank');
+        $this->addSql('DROP TABLE payment_type');
+        $this->addSql('DROP TABLE payment_delay');
+        $this->addSql('DROP TABLE tva_mode');
+
+        // Retire uniquement les 4 types seedes par cette migration. Les autres
+        // types eventuels (CRUD futur) sont preserves.
+        $this->addSql(<<<'SQL'
+            DELETE FROM category_type WHERE code IN ('DISTRIBUTEUR', 'COURTIER', 'SECTEUR', 'AUTRE')
+            SQL);
+    }
+
+    // =================================================================
+    // Referentiels comptables (4 tables statiques, memes colonnes)
+    // =================================================================
+
+    private function createAccountingReferentials(): void
+    {
+        $referentials = [
+            'tva_mode'      => 'Referentiel des modes de TVA appliques a un client (France, Export, Intracom).',
+            'payment_delay' => 'Referentiel des delais de reglement (15 jours, 30 jours, a reception).',
+            'payment_type'  => 'Referentiel des types de reglement (virement, LCR, cheque, non soumise).',
+            'bank'          => 'Referentiel des banques selectionnables pour le reglement par virement.',
+        ];
+
+        foreach ($referentials as $table => $tableComment) {
+            $this->addSql(sprintf(<<<'SQL'
+                CREATE TABLE %s (
+                    id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                    code VARCHAR(30) NOT NULL,
+                    label VARCHAR(120) NOT NULL,
+                    position INT DEFAULT 0 NOT NULL,
+                    PRIMARY KEY (id)
+                )
+                SQL, $table));
+            $this->addSql(sprintf('CREATE UNIQUE INDEX uq_%s_code ON %s (code)', $table, $table));
+
+            $this->comment($table, '_table', $tableComment);
+            $this->comment($table, 'id', 'Identifiant interne auto-incremente.');
+            $this->comment($table, 'code', 'Code technique stable (UPPER_SNAKE, ≤ 30 caracteres) — unique, utilise par le code metier.');
+            $this->comment($table, 'label', 'Libelle affichable (FR, ≤ 120 caracteres).');
+            $this->comment($table, 'position', 'Ordre d affichage croissant dans les selecteurs (tri position ASC puis label ASC).');
+        }
+
+        // Seed initial (cf. spec § 3.2). Tables fraichement creees donc vides :
+        // INSERT direct sans ON CONFLICT.
+        $this->addSql(<<<'SQL'
+            INSERT INTO tva_mode (code, label, position) VALUES
+                ('FRANCE_VENTES',   'France (ventes)',    10),
+                ('EXPORT_VENTES',   'Export (ventes)',    20),
+                ('INTRACOM_VENTES', 'Intracom (ventes)',  30)
+            SQL);
+        $this->addSql(<<<'SQL'
+            INSERT INTO payment_delay (code, label, position) VALUES
+                ('J15',         '15 jours',     10),
+                ('J30',         '30 jours',     20),
+                ('A_RECEPTION', 'À réception',  30)
+            SQL);
+        $this->addSql(<<<'SQL'
+            INSERT INTO payment_type (code, label, position) VALUES
+                ('VIREMENT',    'Virement',     10),
+                ('LCR',         'LCR',          20),
+                ('NON_SOUMISE', 'Non soumise',  30),
+                ('CHEQUE',      'Chèque',       40)
+            SQL);
+        $this->addSql(<<<'SQL'
+            INSERT INTO bank (code, label, position) VALUES
+                ('SG',  'Société Générale', 10),
+                ('CIC', 'CIC',              20),
+                ('CA',  'Crédit Agricole',  30)
+            SQL);
+    }
+
+    // =================================================================
+    // Table principale `client`
+    // =================================================================
+
+    private function createClientTable(): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client (
+                id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                company_name VARCHAR(180) NOT NULL,
+                first_name VARCHAR(120) DEFAULT NULL,
+                last_name VARCHAR(120) DEFAULT NULL,
+                phone_primary VARCHAR(20) NOT NULL,
+                phone_secondary VARCHAR(20) DEFAULT NULL,
+                email VARCHAR(180) NOT NULL,
+                distributor_id INT DEFAULT NULL,
+                broker_id INT DEFAULT NULL,
+                triage_service BOOLEAN DEFAULT FALSE NOT NULL,
+                description TEXT DEFAULT NULL,
+                competitors VARCHAR(255) DEFAULT NULL,
+                founded_at DATE DEFAULT NULL,
+                employees_count INT DEFAULT NULL,
+                revenue_amount NUMERIC(15, 2) DEFAULT NULL,
+                director_name VARCHAR(120) DEFAULT NULL,
+                profit_amount NUMERIC(15, 2) DEFAULT NULL,
+                siren VARCHAR(20) DEFAULT NULL,
+                account_number VARCHAR(40) DEFAULT NULL,
+                tva_mode_id INT DEFAULT NULL,
+                n_tva VARCHAR(40) DEFAULT NULL,
+                payment_delay_id INT DEFAULT NULL,
+                payment_type_id INT DEFAULT NULL,
+                bank_id INT DEFAULT NULL,
+                is_archived BOOLEAN DEFAULT FALSE NOT NULL,
+                archived_at TIMESTAMP(0) WITHOUT TIME ZONE DEFAULT NULL,
+                deleted_at TIMESTAMP(0) WITHOUT TIME ZONE DEFAULT NULL,
+                created_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                updated_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                created_by INT DEFAULT NULL,
+                updated_by INT DEFAULT NULL,
+                PRIMARY KEY (id),
+                CONSTRAINT chk_client_distrib_or_broker
+                    CHECK (NOT (distributor_id IS NOT NULL AND broker_id IS NOT NULL)),
+                CONSTRAINT fk_client_distributor
+                    FOREIGN KEY (distributor_id) REFERENCES client (id) ON DELETE SET NULL,
+                CONSTRAINT fk_client_broker
+                    FOREIGN KEY (broker_id) REFERENCES client (id) ON DELETE SET NULL,
+                CONSTRAINT fk_client_tva_mode
+                    FOREIGN KEY (tva_mode_id) REFERENCES tva_mode (id) ON DELETE RESTRICT,
+                CONSTRAINT fk_client_payment_delay
+                    FOREIGN KEY (payment_delay_id) REFERENCES payment_delay (id) ON DELETE RESTRICT,
+                CONSTRAINT fk_client_payment_type
+                    FOREIGN KEY (payment_type_id) REFERENCES payment_type (id) ON DELETE RESTRICT,
+                CONSTRAINT fk_client_bank
+                    FOREIGN KEY (bank_id) REFERENCES bank (id) ON DELETE RESTRICT,
+                CONSTRAINT fk_client_created_by
+                    FOREIGN KEY (created_by) REFERENCES "user" (id) ON DELETE SET NULL,
+                CONSTRAINT fk_client_updated_by
+                    FOREIGN KEY (updated_by) REFERENCES "user" (id) ON DELETE SET NULL
+            )
+            SQL);
+
+        $this->addSql('CREATE INDEX idx_client_is_archived ON client (is_archived)');
+        $this->addSql('CREATE INDEX idx_client_deleted_at ON client (deleted_at)');
+        $this->addSql('CREATE INDEX idx_client_distributor_id ON client (distributor_id)');
+        $this->addSql('CREATE INDEX idx_client_broker_id ON client (broker_id)');
+        $this->addSql('CREATE INDEX idx_client_created_by ON client (created_by)');
+        $this->addSql('CREATE INDEX idx_client_updated_by ON client (updated_by)');
+
+        // Unicite metier partielle (Q4) : nom de societe insensible a la casse,
+        // parmi les non-archives ET non soft-deletes uniquement. Pas d'index
+        // unique sur siren ni email.
+        $this->addSql(<<<'SQL'
+            CREATE UNIQUE INDEX uq_client_company_name_active
+            ON client (LOWER(company_name))
+            WHERE is_archived = FALSE AND deleted_at IS NULL
+            SQL);
+
+        $this->comment('client', '_table', 'Repertoire clients (M1 Commercial) — entites archivables (is_archived) et soft-deletables (deleted_at, HP M2).');
+        $this->comment('client', 'id', 'Identifiant interne auto-incremente.');
+        $this->comment('client', 'company_name', 'Raison sociale (stockee en MAJUSCULES, RG-1.18). Unique case-insensitive parmi les actifs non archives/non supprimes (RG-1.16, uq_client_company_name_active).');
+        $this->comment('client', 'first_name', 'Prenom du contact principal (capitalise serveur, RG-1.19). first_name OU last_name obligatoire (RG-1.01).');
+        $this->comment('client', 'last_name', 'Nom du contact principal (capitalise serveur, RG-1.19). first_name OU last_name obligatoire (RG-1.01).');
+        $this->comment('client', 'phone_primary', 'Telephone principal — stocke en chiffres uniquement (RG-1.20). Obligatoire.');
+        $this->comment('client', 'phone_secondary', 'Telephone secondaire optionnel — chiffres uniquement (RG-1.20).');
+        $this->comment('client', 'email', 'Email principal (lowercase serveur, RG-1.21). NON unique (RG-1.17 supprimee, Q4).');
+        $this->comment('client', 'distributor_id', 'FK auto-referente vers un client porteur de la categorie DISTRIBUTEUR — exclusive avec broker_id (RG-1.03, chk_client_distrib_or_broker). FK -> client.id, ON DELETE SET NULL.');
+        $this->comment('client', 'broker_id', 'FK auto-referente vers un client porteur de la categorie COURTIER — exclusive avec distributor_id (RG-1.03). FK -> client.id, ON DELETE SET NULL.');
+        $this->comment('client', 'triage_service', 'Drapeau service triage active pour le client. Faux par defaut.');
+        $this->comment('client', 'description', 'Onglet Information : description libre. Obligatoire pour le role Commerciale (RG-1.04), optionnel sinon.');
+        $this->comment('client', 'competitors', 'Onglet Information : concurrents identifies (texte libre ≤ 255). Obligatoire role Commerciale (RG-1.04).');
+        $this->comment('client', 'founded_at', 'Onglet Information : date de creation de l entreprise. Obligatoire role Commerciale (RG-1.04).');
+        $this->comment('client', 'employees_count', 'Onglet Information : effectif (entier >= 0). Obligatoire role Commerciale (RG-1.04).');
+        $this->comment('client', 'revenue_amount', 'Onglet Information : chiffre d affaires (NUMERIC 15,2). Obligatoire role Commerciale (RG-1.04).');
+        $this->comment('client', 'director_name', 'Onglet Information : nom du dirigeant. Obligatoire role Commerciale (RG-1.04).');
+        $this->comment('client', 'profit_amount', 'Onglet Information : resultat / benefice (NUMERIC 15,2). Obligatoire role Commerciale (RG-1.04).');
+        $this->comment('client', 'siren', 'Onglet Comptabilite : SIREN (9 chiffres attendus). NON unique — peut etre partage entre etablissements (RG-1.15 supprimee, Q4).');
+        $this->comment('client', 'account_number', 'Onglet Comptabilite : numero de compte comptable du client.');
+        $this->comment('client', 'tva_mode_id', 'Onglet Comptabilite : mode de TVA applique — FK -> tva_mode.id, ON DELETE RESTRICT.');
+        $this->comment('client', 'n_tva', 'Onglet Comptabilite : numero de TVA intracommunautaire.');
+        $this->comment('client', 'payment_delay_id', 'Onglet Comptabilite : delai de reglement — FK -> payment_delay.id, ON DELETE RESTRICT.');
+        $this->comment('client', 'payment_type_id', 'Onglet Comptabilite : type de reglement — FK -> payment_type.id, ON DELETE RESTRICT. Code LCR impose >= 1 RIB (RG-1.13), VIREMENT impose une banque (RG-1.12).');
+        $this->comment('client', 'bank_id', 'Onglet Comptabilite : banque — FK -> bank.id, ON DELETE RESTRICT. Obligatoire si payment_type = VIREMENT (RG-1.12).');
+        $this->comment('client', 'is_archived', 'Drapeau fonctionnel d archivage — masque par defaut dans la liste. Bascule via permission commercial.clients.archive (RG-1.22/23).');
+        $this->comment('client', 'archived_at', 'Horodatage de l archivage — pose quand is_archived passe a vrai, remis a null a la restauration (RG-1.22/23).');
+        $this->comment('client', 'deleted_at', 'Horodatage du soft-delete technique (HP M2) — non expose par l API au M1. Null = ligne active.');
+        $this->addTimestampableBlamableComments('client');
+    }
+
+    // =================================================================
+    // M2M client <-> category
+    // =================================================================
+
+    private function createClientCategory(): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_category (
+                client_id INT NOT NULL,
+                category_id INT NOT NULL,
+                PRIMARY KEY (client_id, category_id),
+                CONSTRAINT fk_client_category_client
+                    FOREIGN KEY (client_id) REFERENCES client (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_category_category
+                    FOREIGN KEY (category_id) REFERENCES category (id) ON DELETE RESTRICT
+            )
+            SQL);
+        $this->addSql('CREATE INDEX idx_client_category_category ON client_category (category_id)');
+
+        $this->comment('client_category', '_table', 'Jointure M2M client <-> category (Catalog) — categories metier du client (au moins une obligatoire).');
+        $this->comment('client_category', 'client_id', 'FK -> client.id, ON DELETE CASCADE — client porteur de la categorie.');
+        $this->comment('client_category', 'category_id', 'FK -> category.id, ON DELETE RESTRICT — categorie rattachee au client.');
+    }
+
+    // =================================================================
+    // Sous-collection : contacts (1:n)
+    // =================================================================
+
+    private function createClientContact(): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_contact (
+                id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                client_id INT NOT NULL,
+                first_name VARCHAR(120) DEFAULT NULL,
+                last_name VARCHAR(120) DEFAULT NULL,
+                job_title VARCHAR(120) DEFAULT NULL,
+                phone_primary VARCHAR(20) DEFAULT NULL,
+                phone_secondary VARCHAR(20) DEFAULT NULL,
+                email VARCHAR(180) DEFAULT NULL,
+                position INT DEFAULT 0 NOT NULL,
+                created_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                updated_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                created_by INT DEFAULT NULL,
+                updated_by INT DEFAULT NULL,
+                PRIMARY KEY (id),
+                CONSTRAINT chk_client_contact_name
+                    CHECK (first_name IS NOT NULL OR last_name IS NOT NULL),
+                CONSTRAINT fk_client_contact_client
+                    FOREIGN KEY (client_id) REFERENCES client (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_contact_created_by
+                    FOREIGN KEY (created_by) REFERENCES "user" (id) ON DELETE SET NULL,
+                CONSTRAINT fk_client_contact_updated_by
+                    FOREIGN KEY (updated_by) REFERENCES "user" (id) ON DELETE SET NULL
+            )
+            SQL);
+        $this->addSql('CREATE INDEX idx_client_contact_client ON client_contact (client_id)');
+
+        $this->comment('client_contact', '_table', 'Contacts d un client (1:n) — au moins firstName OU lastName par contact (RG-1.05).');
+        $this->comment('client_contact', 'id', 'Identifiant interne auto-incremente.');
+        $this->comment('client_contact', 'client_id', 'FK -> client.id, ON DELETE CASCADE — client proprietaire du contact.');
+        $this->comment('client_contact', 'first_name', 'Prenom du contact (capitalise serveur). first_name OU last_name obligatoire (RG-1.05, chk_client_contact_name).');
+        $this->comment('client_contact', 'last_name', 'Nom du contact (capitalise serveur). first_name OU last_name obligatoire (RG-1.05, chk_client_contact_name).');
+        $this->comment('client_contact', 'job_title', 'Fonction / intitule de poste du contact (≤ 120 caracteres).');
+        $this->comment('client_contact', 'phone_primary', 'Telephone principal du contact — chiffres uniquement (RG-1.20).');
+        $this->comment('client_contact', 'phone_secondary', 'Telephone secondaire du contact — chiffres uniquement (RG-1.20).');
+        $this->comment('client_contact', 'email', 'Email du contact (lowercase serveur, RG-1.21).');
+        $this->comment('client_contact', 'position', 'Ordre d affichage du contact dans la liste du client (croissant).');
+        $this->addTimestampableBlamableComments('client_contact');
+    }
+
+    // =================================================================
+    // Sous-collection : adresses (1:n)
+    // =================================================================
+
+    private function createClientAddress(): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_address (
+                id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                client_id INT NOT NULL,
+                is_prospect BOOLEAN DEFAULT FALSE NOT NULL,
+                is_delivery BOOLEAN DEFAULT FALSE NOT NULL,
+                is_billing BOOLEAN DEFAULT FALSE NOT NULL,
+                country VARCHAR(80) DEFAULT 'France' NOT NULL,
+                postal_code VARCHAR(20) NOT NULL,
+                city VARCHAR(120) NOT NULL,
+                street VARCHAR(255) NOT NULL,
+                street_complement VARCHAR(255) DEFAULT NULL,
+                billing_email VARCHAR(180) DEFAULT NULL,
+                position INT DEFAULT 0 NOT NULL,
+                created_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                updated_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                created_by INT DEFAULT NULL,
+                updated_by INT DEFAULT NULL,
+                PRIMARY KEY (id),
+                CONSTRAINT chk_client_address_prospect_exclusive
+                    CHECK (NOT (is_prospect = TRUE AND (is_delivery = TRUE OR is_billing = TRUE))),
+                CONSTRAINT chk_client_address_billing_email
+                    CHECK ((is_billing = FALSE AND billing_email IS NULL)
+                        OR (is_billing = TRUE AND billing_email IS NOT NULL)),
+                CONSTRAINT fk_client_address_client
+                    FOREIGN KEY (client_id) REFERENCES client (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_address_created_by
+                    FOREIGN KEY (created_by) REFERENCES "user" (id) ON DELETE SET NULL,
+                CONSTRAINT fk_client_address_updated_by
+                    FOREIGN KEY (updated_by) REFERENCES "user" (id) ON DELETE SET NULL
+            )
+            SQL);
+        $this->addSql('CREATE INDEX idx_client_address_client ON client_address (client_id)');
+
+        $this->comment('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).');
+        $this->comment('client_address', 'id', 'Identifiant interne auto-incremente.');
+        $this->comment('client_address', 'client_id', 'FK -> client.id, ON DELETE CASCADE — client proprietaire de l adresse.');
+        $this->comment('client_address', 'is_prospect', 'Adresse de prospection — exclusive de is_delivery/is_billing (RG-1.06/07/08, chk_client_address_prospect_exclusive). Faux par defaut.');
+        $this->comment('client_address', 'is_delivery', 'Adresse de livraison. Exclusive de is_prospect. Faux par defaut.');
+        $this->comment('client_address', 'is_billing', 'Adresse de facturation. Exclusive de is_prospect. Impose billing_email (RG-1.11). Faux par defaut.');
+        $this->comment('client_address', 'country', 'Pays de l adresse — defaut France.');
+        $this->comment('client_address', 'postal_code', 'Code postal (4-5 chiffres attendus, RG-1.09).');
+        $this->comment('client_address', 'city', 'Ville — preremplie depuis le code postal via API BAN cote front (RG-1.09).');
+        $this->comment('client_address', 'street', 'Numero et voie de l adresse.');
+        $this->comment('client_address', 'street_complement', 'Complement d adresse (etage, batiment...) — optionnel.');
+        $this->comment('client_address', 'billing_email', 'Email de facturation — obligatoire si is_billing, null sinon (RG-1.11, chk_client_address_billing_email).');
+        $this->comment('client_address', 'position', 'Ordre d affichage de l adresse dans la liste du client (croissant).');
+        $this->addTimestampableBlamableComments('client_address');
+    }
+
+    // =================================================================
+    // Jointures de client_address (M2M)
+    // =================================================================
+
+    private function createClientAddressJoinTables(): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_address_site (
+                client_address_id INT NOT NULL,
+                site_id INT NOT NULL,
+                PRIMARY KEY (client_address_id, site_id),
+                CONSTRAINT fk_client_address_site_address
+                    FOREIGN KEY (client_address_id) REFERENCES client_address (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_address_site_site
+                    FOREIGN KEY (site_id) REFERENCES site (id) ON DELETE RESTRICT
+            )
+            SQL);
+        $this->comment('client_address_site', '_table', 'Jointure M2M client_address <-> site (Sites) — sites desservis par l adresse (>= 1 obligatoire, RG-1.10).');
+        $this->comment('client_address_site', 'client_address_id', 'FK -> client_address.id, ON DELETE CASCADE — adresse concernee.');
+        $this->comment('client_address_site', 'site_id', 'FK -> site.id, ON DELETE RESTRICT — site rattache a l adresse.');
+
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_address_contact (
+                client_address_id INT NOT NULL,
+                client_contact_id INT NOT NULL,
+                PRIMARY KEY (client_address_id, client_contact_id),
+                CONSTRAINT fk_client_address_contact_address
+                    FOREIGN KEY (client_address_id) REFERENCES client_address (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_address_contact_contact
+                    FOREIGN KEY (client_contact_id) REFERENCES client_contact (id) ON DELETE CASCADE
+            )
+            SQL);
+        $this->comment('client_address_contact', '_table', 'Jointure M2M client_address <-> client_contact — contacts associes a une adresse.');
+        $this->comment('client_address_contact', 'client_address_id', 'FK -> client_address.id, ON DELETE CASCADE — adresse concernee.');
+        $this->comment('client_address_contact', 'client_contact_id', 'FK -> client_contact.id, ON DELETE CASCADE — contact associe a l adresse.');
+
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_address_category (
+                client_address_id INT NOT NULL,
+                category_id INT NOT NULL,
+                PRIMARY KEY (client_address_id, category_id),
+                CONSTRAINT fk_client_address_category_address
+                    FOREIGN KEY (client_address_id) REFERENCES client_address (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_address_category_category
+                    FOREIGN KEY (category_id) REFERENCES category (id) ON DELETE RESTRICT
+            )
+            SQL);
+        $this->comment('client_address_category', '_table', 'Jointure M2M client_address <-> category — categories d adresse (types SECTEUR/AUTRE uniquement, RG-1.29).');
+        $this->comment('client_address_category', 'client_address_id', 'FK -> client_address.id, ON DELETE CASCADE — adresse concernee.');
+        $this->comment('client_address_category', 'category_id', 'FK -> category.id, ON DELETE RESTRICT — categorie d adresse (type SECTEUR ou AUTRE, RG-1.29).');
+    }
+
+    // =================================================================
+    // Sous-collection : RIB (1:n)
+    // =================================================================
+
+    private function createClientRib(): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE client_rib (
+                id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                client_id INT NOT NULL,
+                label VARCHAR(120) NOT NULL,
+                bic VARCHAR(20) NOT NULL,
+                iban VARCHAR(34) NOT NULL,
+                position INT DEFAULT 0 NOT NULL,
+                created_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                updated_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                created_by INT DEFAULT NULL,
+                updated_by INT DEFAULT NULL,
+                PRIMARY KEY (id),
+                CONSTRAINT fk_client_rib_client
+                    FOREIGN KEY (client_id) REFERENCES client (id) ON DELETE CASCADE,
+                CONSTRAINT fk_client_rib_created_by
+                    FOREIGN KEY (created_by) REFERENCES "user" (id) ON DELETE SET NULL,
+                CONSTRAINT fk_client_rib_updated_by
+                    FOREIGN KEY (updated_by) REFERENCES "user" (id) ON DELETE SET NULL
+            )
+            SQL);
+        $this->addSql('CREATE INDEX idx_client_rib_client ON client_rib (client_id)');
+
+        $this->comment('client_rib', '_table', 'Coordonnees bancaires d un client (1:n) — >= 1 RIB obligatoire si payment_type = LCR (RG-1.13). Tous les champs audites (pas d AuditIgnore).');
+        $this->comment('client_rib', 'id', 'Identifiant interne auto-incremente.');
+        $this->comment('client_rib', 'client_id', 'FK -> client.id, ON DELETE CASCADE — client proprietaire du RIB.');
+        $this->comment('client_rib', 'label', 'Libelle du RIB (ex: compte principal).');
+        $this->comment('client_rib', 'bic', 'Code BIC/SWIFT de la banque (8 ou 11 caracteres).');
+        $this->comment('client_rib', 'iban', 'IBAN du compte (≤ 34 caracteres).');
+        $this->comment('client_rib', 'position', 'Ordre d affichage du RIB dans la liste du client (croissant).');
+        $this->addTimestampableBlamableComments('client_rib');
+    }
+
+    // =================================================================
+    // Seed extension category_type (M0)
+    // =================================================================
+
+    private function seedCategoryTypes(): void
+    {
+        // Idempotent : la table category_type peut deja porter des donnees en
+        // prod. ON CONFLICT (code) s appuie sur l index unique uq_category_type_code.
+        // NB : la table M0 n a pas de colonne `position` (id/code/label seulement),
+        // contrairement au pseudo-SQL de la spec § 3.3.
+        $this->addSql(<<<'SQL'
+            INSERT INTO category_type (code, label) VALUES
+                ('DISTRIBUTEUR', 'Distributeur'),
+                ('COURTIER',     'Courtier'),
+                ('SECTEUR',      'Secteur'),
+                ('AUTRE',        'Autre')
+            ON CONFLICT (code) DO NOTHING
+            SQL);
+    }
+
+    // =================================================================
+    // Helpers
+    // =================================================================
+
+    /**
+     * Pose les 4 commentaires standardises Timestampable/Blamable sur une table,
+     * en reutilisant le catalogue partage (source unique, cf. ERP-67).
+     */
+    private function addTimestampableBlamableComments(string $table): void
+    {
+        foreach (ColumnCommentsCatalog::timestampableBlamableComments() as $column => $description) {
+            $this->comment($table, $column, $description);
+        }
+    }
+
+    /**
+     * Emet un `COMMENT ON TABLE` (colonne speciale `_table`) ou
+     * `COMMENT ON COLUMN` en dollar-quoting Postgres ($_$...$_$) pour eviter
+     * tout echappement d apostrophe.
+     */
+    private function comment(string $table, string $column, string $description): void
+    {
+        $quotedTable = '"'.str_replace('"', '""', $table).'"';
+
+        if ('_table' === $column) {
+            $this->addSql(sprintf('COMMENT ON TABLE %s IS $_$%s$_$', $quotedTable, $description));
+
+            return;
+        }
+
+        $this->addSql(sprintf(
+            'COMMENT ON COLUMN %s.%s IS $_$%s$_$',
+            $quotedTable,
+            '"'.str_replace('"', '""', $column).'"',
+            $description,
+        ));
+    }
+}

src/Module/Catalog/Infrastructure/DataFixtures/CategoryTypeFixtures.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Infrastructure\DataFixtures;
+
+use App\Module\Catalog\Domain\Entity\CategoryType;
+use App\Module\Catalog\Domain\Repository\CategoryTypeRepositoryInterface;
+use Doctrine\Bundle\FixturesBundle\Fixture;
+use Doctrine\Persistence\ObjectManager;
+
+/**
+ * Fixtures du module Catalog : seed des types de categorie metier (M1).
+ *
+ * La table `category_type` est creee vide au M0 ; le M1 la peuple avec les 4
+ * types DISTRIBUTEUR / COURTIER / SECTEUR / AUTRE (cf. spec M1 § 3.3).
+ *
+ * Pourquoi une fixture EN PLUS du seed de la migration (Version20260601000000) :
+ * `category_type` est une entite managee par l ORM, donc le purger Doctrine la
+ * vide avant chaque `doctrine:fixtures:load`. Sans cette fixture, les 4 types
+ * seedes par la migration disparaitraient apres `make db-reset` / setup de test.
+ * Le seed migration couvre la prod (ou les fixtures ne tournent pas) ; cette
+ * fixture re-aligne dev et test. Les deux chemins produisent un etat identique.
+ *
+ * Idempotence : lookup par `code` parmi les types existants avant insertion,
+ * sur le modele d AppFixtures::ensureSystemRole. Rejouable sans doublon meme
+ * si le purger est desactive.
+ */
+class CategoryTypeFixtures extends Fixture
+{
+    /**
+     * Source unique des 4 types metier : code technique => libelle FR.
+     * Doit rester aligne sur le seed de la migration Version20260601000000.
+     */
+    private const TYPES = [
+        'DISTRIBUTEUR' => 'Distributeur',
+        'COURTIER'     => 'Courtier',
+        'SECTEUR'      => 'Secteur',
+        'AUTRE'        => 'Autre',
+    ];
+
+    public function __construct(
+        private readonly CategoryTypeRepositoryInterface $categoryTypeRepository,
+    ) {}
+
+    public function load(ObjectManager $manager): void
+    {
+        // Index des types deja presents par code, pour ne pas creer de doublon.
+        $existingByCode = [];
+        foreach ($this->categoryTypeRepository->findAllOrderedByLabel() as $type) {
+            $existingByCode[$type->getCode()] = $type;
+        }
+
+        foreach (self::TYPES as $code => $label) {
+            $type = $existingByCode[$code] ?? new CategoryType();
+            $type->setCode($code);
+            $type->setLabel($label);
+            $manager->persist($type);
+        }
+
+        $manager->flush();
+    }
+}