espace-paie-odentas/MIGRATION_AVENANTS_AIRTABLE.md

Migration des Avenants depuis Airtable vers Supabase

📋 Contexte

Ce document décrit la procédure de migration des avenants historiques depuis Airtable vers la base de données Supabase. Cette migration permet de centraliser toutes les données d'avenants dans le système Espace Paie.

🎯 Objectif

Migrer 103 avenants depuis Airtable vers la table avenants de Supabase, en préservant les informations essentielles (dates, éléments modifiés, organisation).

📊 Structure des Données

Données Source (Airtable CSV)

Le fichier CSV contient les colonnes suivantes :

Colonne	Description	Exemple
Reference	Référence du contrat concerné	DK1M4LEQ, RG4168801
Structure API	Nom de l'organisation	Association Atelier Moz
Date avenant	Date de signature de l'avenant	3/7/2025
Effet avenant	Date d'effet de l'avenant	3/7/2025
Élément(s) à avenanter	Éléments modifiés	"Durée de l'engagement,Rémunération"

Mapping vers Supabase

Le script effectue le mapping suivant :

Source Airtable	Destination Supabase	Transformation
Reference	Recherche dans cddu_contracts.contract_number ou cddu_contracts.reference	Lookup du contract_id
Date avenant	avenants.date_avenant	Format: D/M/YYYY → YYYY-MM-DD
Effet avenant	avenants.date_effet	Format: D/M/YYYY → YYYY-MM-DD
Élément(s) à avenanter	avenants.elements_avenantes	Parser les éléments (voir ci-dessous)

Parsing des Éléments

Les éléments textuels sont convertis vers les codes du système :

Texte Airtable	Code Supabase
"Durée de l'engagement"	duree
"Rémunération"	remuneration
"Objet"	objet
"Lieu" ou "horaire"	lieu_horaire

Champs Générés Automatiquement

• numero_avenant : Généré automatiquement par organisation (AVE-001, AVE-002, etc.)
• type_avenant : Fixé à "modification" (tous les avenants Airtable sont des modifications)
• statut : Fixé à "signed" (les avenants historiques sont considérés signés)
• signature_status : Fixé à "signed"
• motif_avenant : Texte auto-généré: "Migration depuis Airtable - Éléments: ..."

Champs Non Migrés (NULL)

Les champs suivants restent à NULL pour l'instant :

• objet_data, duree_data, lieu_horaire_data, remuneration_data (détails des modifications)
• pdf_url, pdf_s3_key (PDF non disponibles)
• signed_pdf_s3_key
• docuseal_template_id, docuseal_submission_id
• employer_docuseal_slug, employee_docuseal_slug

🚀 Procédure de Migration

Prérequis

1. Fichier CSV : Placer le fichier Contrats de travail-Tous les CDDU.csv à la racine du projet
2. Variables d'environnement :
   • NEXT_PUBLIC_SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY

Étapes

1. Vérifier les contrats existants

   Avant de lancer la migration, assurez-vous que tous les contrats référencés dans le CSV existent dans Supabase. Le script vous indiquera les contrats manquants.

2. Placer le fichier CSV

   cp "/Users/renaud/Downloads/Contrats de travail-Tous les CDDU.csv" ./
   

3. Exécuter le script de migration

   npx ts-node scripts/migrate-avenants-from-airtable.ts
   

4. Analyser les résultats

   Le script affiche un résumé détaillé :

   • Nombre d'avenants créés
   • Lignes ignorées (sans date d'avenant)
   • Contrats non trouvés
   • Erreurs éventuelles

Exemple de Sortie

🚀 Début de la migration des avenants depuis Airtable

📄 Lecture du fichier: /Users/renaud/Projet Nouvel Espace Paie/Contrats de travail-Tous les CDDU.csv

📊 Nombre total de lignes: 103

[1/103] Traitement de DK1M4LEQ
   ✅ Contrat trouvé: DK1M4LEQ (Association Atelier Moz)
   ✅ Avenant créé: AVE-001 (Date: 2025-07-03)

[2/103] Traitement de 14SJX34R
   ✅ Contrat trouvé: 14SJX34R (La Petite Légèreté)
   ✅ Avenant créé: AVE-001 (Date: 2025-06-14)

...

============================================================
📊 RÉSUMÉ DE LA MIGRATION
============================================================
Total de lignes:           103
Avenants créés:            95 ✅
Lignes ignorées:           5 ⏭️
Contrats non trouvés:      3 ❌
Erreurs:                   0 ❌
============================================================

⚠️  Contrats non trouvés dans Supabase:
   - RG4168801
   - RG8698859
   - RG88658839

💡 Ces contrats doivent être migrés avant de créer leurs avenants

✅ Migration terminée!

📝 Notes Importantes

Contrats RG (Régime Général)

Les contrats commençant par RG sont des contrats en Régime Général. Assurez-vous qu'ils sont bien présents dans cddu_contracts avant la migration.

Lignes sans Date

Certaines lignes du CSV n'ont pas de date d'avenant. Ces lignes sont automatiquement ignorées par le script (comptabilisées dans "Lignes ignorées").

Numérotation des Avenants

La numérotation des avenants (AVE-001, AVE-002, etc.) est par organisation. Chaque organisation a sa propre séquence de numéros d'avenants.

Statut des Avenants

Tous les avenants migrés sont créés avec :

• Statut : signed (signés)
• Signature Status : signed

Cela reflète le fait que ces avenants historiques ont déjà été traités et signés dans Airtable.

🔧 Dépannage

Erreur : "Contrat non trouvé"

Si le script ne trouve pas un contrat, vérifiez :

1. La référence du contrat dans le CSV
2. La colonne contract_number ou reference dans cddu_contracts
3. Que le contrat n'a pas été supprimé

Erreur : "Dates invalides"

Vérifiez le format des dates dans le CSV. Le format attendu est D/M/YYYY ou DD/MM/YYYY.

Erreur : "Variables d'environnement manquantes"

Assurez-vous que votre fichier .env.local contient :

NEXT_PUBLIC_SUPABASE_URL=https://votre-projet.supabase.co
SUPABASE_SERVICE_ROLE_KEY=votre-clé-service-role

✅ Vérification Post-Migration

Après la migration, vérifiez les données dans Supabase :

-- Compter les avenants par organisation
SELECT 
  o.name,
  COUNT(a.id) as nb_avenants
FROM avenants a
JOIN cddu_contracts c ON a.contract_id = c.id
JOIN organizations o ON c.org_id = o.id
GROUP BY o.name
ORDER BY nb_avenants DESC;

-- Vérifier les avenants migrés depuis Airtable
SELECT 
  a.numero_avenant,
  c.contract_number,
  a.date_avenant,
  a.date_effet,
  a.elements_avenantes,
  a.statut
FROM avenants a
JOIN cddu_contracts c ON a.contract_id = c.id
WHERE a.motif_avenant LIKE 'Migration depuis Airtable%'
ORDER BY a.date_avenant DESC
LIMIT 20;

🎯 Prochaines Étapes

Après la migration des données :

1. Récupération des PDF : Les PDF des avenants signés doivent être récupérés depuis Airtable et uploadés sur S3
2. Mise à jour des données détaillées : Si possible, compléter les champs objet_data, duree_data, etc. avec les vraies valeurs
3. Vérification manuelle : Passer en revue quelques avenants pour s'assurer de la cohérence des données

📚 Références

• Table Supabase : avenants
• Script de migration : scripts/migrate-avenants-from-airtable.ts
• Fichier source : Contrats de travail-Tous les CDDU.csv
• Type TypeScript : types/amendments.ts

---

Date de création : 5 novembre 2025
Auteur : Migration automatisée Airtable → Supabase