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

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

3. **Exécuter le script de migration**

   ```bash
   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 :

```env
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 :

```sql
-- 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