chore(migration) : outils d'extraction des tiers Mixgraine (WIP)

Boite a outils de migration des tiers (clients / fournisseurs / prestataires)
depuis l'ancien CRM Mixgraine vers Starseed :

- extract_mixgraine.py : extraction + normalisation via l'API Mixgraine (cache
  disque reprenable, debit ~1 req/s, backoff 429/5xx) -> JSON format Starseed
- build_tiers_xlsx.py  : Excel de relecture (1 onglet par type + Synthese,
  colonne 'Site manquant' filtrable)
- run.sh               : enchaine extraction + Excel
- README.md            : prerequis, recuperation du token, lancement
- mixgraine-migration-analysis.md : analyse + mapping des champs Mixgraine -> Starseed

WIP : les commandes d'import Symfony cote Starseed (seed referentiels/sites,
import Client/Supplier/Provider, 2e passe distributeur/courtier) restent a faire.

Le dossier de sortie mixgraine-export/ (IBAN/BIC + PII reelles) est volontairement
.gitignore : reproductible localement via MIXGRAINE_JWT.

docs/migration/README.md

@@ -0,0 +1,80 @@
+# Migration Mixgraine → Starseed — Outils
+
+Boîte à outils pour migrer les tiers (clients / fournisseurs / prestataires) depuis
+le CRM Mixgraine vers Starseed. Tout est autonome : 2 scripts Python + ce README.
+
+| Fichier | Rôle |
+|---|---|
+| `mixgraine-migration-analysis.md` | Rapport d'analyse + mapping des champs (à lire en premier) |
+| `extract_mixgraine.py` | Récupère les tiers depuis l'API Mixgraine et les normalise en JSON |
+| `build_tiers_xlsx.py` | Produit un Excel avec **un onglet par type** + filtre « Site manquant » |
+| `run.sh` | Enchaîne les deux scripts |
+
+---
+
+## Prérequis
+
+- **Python 3** (déjà présent sur un poste Linux/Mac) — vérifier : `python3 --version`
+- **openpyxl** (pour les Excel) : `pip install openpyxl` (ou `pip install --break-system-packages openpyxl`)
+- Un **token Mixgraine** (JWT) valide — voir ci-dessous.
+
+### Récupérer le token Mixgraine
+
+1. Ouvrir `https://liot.mixsuite.fr` dans Chrome, connecté.
+2. Ouvrir les outils dev (F12) → onglet **Network**.
+3. Cliquer sur n'importe quelle liste (clients…) pour déclencher un appel `api/customer`.
+4. Cliquer sur la requête → **Headers** → copier la valeur après `authorization: Bearer ` (la longue chaîne `eyJ0eXAi...`).
+
+> Le token expire au bout de quelques jours. S'il est expiré, en récupérer un nouveau de la même façon. **Ne jamais le committer dans git.**
+
+---
+
+## Lancement
+
+### Méthode simple (script tout-en-un)
+
+```bash
+cd docs/migration
+export MIXGRAINE_JWT="eyJ0eXAi...colle-ton-token-ici..."
+./run.sh
+```
+
+### Ou étape par étape
+
+```bash
+cd docs/migration
+export MIXGRAINE_JWT="eyJ0eXAi..."
+
+# 1) Extraction + normalisation (lent : ~1 requête/seconde, soyez patient)
+python3 extract_mixgraine.py
+#   -> écrit dans ./mixgraine-export/ : clients.json, suppliers.json,
+#      providers.json, referentials.json, extraction-report.txt
+#   Test rapide sur 20 tiers : python3 extract_mixgraine.py --limit-ids 20
+
+# 2) Génération de l'Excel de relecture (un onglet par type)
+python3 build_tiers_xlsx.py --in mixgraine-export
+#   -> mixgraine-export/mixgraine-tiers.xlsx
+#      onglets Clients / Fournisseurs / Prestataires + Synthèse,
+#      colonne « Site manquant » filtrable, lignes à problème surlignées
+```
+
+---
+
+## Ce que tu obtiens
+
+Tout est écrit dans `docs/migration/mixgraine-export/` :
+
+- **`*.json`** — données normalisées au format Starseed (utilisées plus tard par les commandes d'import).
+- **`mixgraine-tiers.xlsx`** — un onglet par type (**Clients / Fournisseurs / Prestataires**) + un onglet **Synthèse**. Chaque onglet liste toutes les données (une ligne par adresse), avec une colonne **Site manquant** (OUI/vide) et une colonne **Problèmes**. Le **filtre automatique** est activé : clique l'entonnoir de la colonne « Site manquant » → coche `OUI` pour isoler les adresses sans site.
+- **`extraction-report.txt`** — compteurs + avertissements.
+- **`cache/`** — réponses brutes par tiers (permet de relancer sans tout refetch).
+
+**Workflow conseillé** : ouvrir `mixgraine-tiers.xlsx`, filtrer « Site manquant = OUI » dans chaque onglet, corriger la donnée **à la source dans Mixgraine** (re-cocher les organisations/sites, compléter les emails de facturation), puis relancer (le cache accélère).
+
+---
+
+## Notes
+
+- L'extraction est **reprenable** : si elle s'interrompt, relance-la, elle repart du cache.
+- Le débit est volontairement lent (`--delay 1.0` par défaut) pour ne pas saturer le serveur. Pour aller plus vite (à tes risques) : `--delay 0.3`.
+- Le dossier `mixgraine-export/` n'a pas vocation à être committé (données + token-sensible). Pense à l'ajouter au `.gitignore` si besoin.