# Intégration Twenty CRM dans le Widget Devoirs

## 📋 Vue d'ensemble

Le widget "Devoirs" affiche maintenant les tâches en retard provenant de **deux sources** :
1. **Leantime** (agilite.slm-lab.net)
2. **Twenty CRM** (mediation.slm-lab.net)

Les tâches sont combinées, filtrées (uniquement celles en retard), triées par date d'échéance, et limitées à 7 tâches.

---

## 🔧 Configuration Requise

### Variables d'Environnement

Ajoutez les variables suivantes à votre fichier `.env.local` (développement) ou à vos variables d'environnement de production :

```env
# Twenty CRM API Configuration
TWENTY_CRM_API_URL=https://mediation.slm-lab.net/graphql
TWENTY_CRM_API_KEY=your_api_key_here
TWENTY_CRM_URL=https://mediation.slm-lab.net
```

**Où obtenir la clé API :**
1. Connectez-vous à Twenty CRM (mediation.slm-lab.net)
2. Allez dans **Settings → APIs & Webhooks**
3. Cliquez sur **"+ Create key"**
4. Donnez un nom à la clé (ex: "NeahStable Widget")
5. Copiez la clé (elle ne sera affichée qu'une seule fois)

---

## 📁 Fichiers Créés/Modifiés

### Nouveau Fichier
- **`app/api/twenty-crm/tasks/route.ts`** - Endpoint API pour récupérer les tâches Twenty CRM

### Fichiers Modifiés
- **`components/flow.tsx`** - Widget Devoirs modifié pour combiner les deux sources

---

## 🔄 Flow de Fonctionnement

### 1. Récupération des Tâches

Le widget fait **deux appels API en parallèle** :

```typescript
const [leantimeResponse, twentyCrmResponse] = await Promise.allSettled([
  fetch('/api/leantime/tasks'),
  fetch('/api/twenty-crm/tasks'),
]);
```

**Avantages :**
- ✅ Appels parallèles = plus rapide
- ✅ `Promise.allSettled` = si une source échoue, l'autre continue de fonctionner
- ✅ Pas de dépendance entre les deux sources

### 2. Transformation des Tâches Twenty CRM

Les tâches Twenty CRM sont transformées pour correspondre au format Leantime :

```typescript
{
  id: `twenty-${task.id}`, // Préfixe pour éviter les conflits
  headline: task.title,
  dateToFinish: task.dueAt,
  projectName: 'Twenty CRM',
  source: 'twenty-crm', // Identifiant de source
  url: `${TWENTY_CRM_URL}/object/activity/${task.id}`, // Lien direct
  // ... autres champs
}
```

### 3. Filtrage et Tri

1. **Filtrage :** Uniquement les tâches avec date d'échéance **avant aujourd'hui** (en retard)
2. **Tri :** Par date d'échéance (plus anciennes en premier)
3. **Limite :** Maximum 7 tâches affichées

### 4. Affichage

- Les tâches Twenty CRM sont identifiées par un badge "(Twenty CRM)"
- Le lien pointe vers la page de la tâche dans Twenty CRM
- Le format d'affichage est identique pour les deux sources

---

## 🔍 Structure de l'API Twenty CRM

### Endpoint GraphQL

**URL :** `https://mediation.slm-lab.net/graphql`

**Méthode :** POST

**Headers :**
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### Requête GraphQL

```graphql
query GetOverdueTasks {
  findManyActivities(
    filter: {
      type: { eq: Task }
      completedAt: { is: NULL }
      dueAt: { lt: "2026-01-15T00:00:00Z" }
    }
    orderBy: { dueAt: AscNullsLast }
  ) {
    edges {
      node {
        id
        title
        body
        dueAt
        completedAt
        type
        assigneeId
        assignee {
          id
          firstName
          lastName
          email
        }
      }
    }
  }
}
```

**Filtres appliqués :**
- `type: { eq: Task }` - Uniquement les tâches (pas les autres activités)
- `completedAt: { is: NULL }` - Uniquement les tâches non complétées
- `dueAt: { lt: "..." }` - Uniquement les tâches avec date d'échéance avant aujourd'hui

---

## 🐛 Dépannage

### Erreur : "TWENTY_CRM_API_URL is not set"

**Solution :** Ajoutez `TWENTY_CRM_API_URL` à vos variables d'environnement.

### Erreur : "TWENTY_CRM_API_KEY is not set"

**Solution :** Ajoutez `TWENTY_CRM_API_KEY` à vos variables d'environnement.

### Erreur : "401 Unauthorized"

**Causes possibles :**
- Clé API invalide ou expirée
- Clé API mal copiée (espaces, caractères invisibles)
- Permissions insuffisantes sur la clé API

**Solution :**
1. Vérifiez que la clé API est correctement copiée
2. Régénérez la clé API dans Twenty CRM
3. Vérifiez les permissions de la clé API

### Erreur : "GraphQL errors from Twenty CRM"

**Causes possibles :**
- Structure de la requête GraphQL incorrecte
- Version de Twenty CRM incompatible
- Schéma GraphQL différent selon le workspace

**Solution :**
1. Vérifiez la documentation de votre version de Twenty CRM
2. Testez la requête GraphQL directement dans l'interface GraphQL de Twenty CRM
3. Ajustez la requête selon votre schéma

### Aucune tâche Twenty CRM n'apparaît

**Vérifications :**
1. ✅ Vérifiez qu'il existe des tâches en retard dans Twenty CRM
2. ✅ Vérifiez que les tâches ont une date d'échéance (`dueAt`)
3. ✅ Vérifiez que les tâches ne sont pas complétées (`completedAt` est NULL)
4. ✅ Vérifiez les logs du serveur pour voir les erreurs éventuelles

---

## 📊 Logs et Debug

### Logs Backend

Tous les logs sont préfixés avec `[TWENTY_CRM_TASKS]` :

```typescript
logger.debug('[TWENTY_CRM_TASKS] Fetching tasks from Twenty CRM', {...});
logger.error('[TWENTY_CRM_TASKS] Failed to fetch tasks', {...});
```

### Logs Frontend

Le widget affiche dans la console :
- Nombre de tâches Leantime récupérées
- Nombre de tâches Twenty CRM récupérées
- Total combiné
- Tâches triées avec leur source

---

## 🔄 Alternatives si GraphQL ne fonctionne pas

Si la requête GraphQL ne fonctionne pas avec votre version de Twenty CRM, vous pouvez utiliser l'API REST :

### Option 1 : API REST (si disponible)

```typescript
const response = await fetch(`${process.env.TWENTY_CRM_API_URL}/api/activities`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.TWENTY_CRM_API_KEY}`,
  },
});
```

### Option 2 : Ajuster la requête GraphQL

La structure exacte peut varier. Consultez la documentation de votre instance Twenty CRM ou utilisez l'explorateur GraphQL intégré.

---

## ✅ Checklist de Déploiement

- [ ] Variables d'environnement configurées :
  - [ ] `TWENTY_CRM_API_URL`
  - [ ] `TWENTY_CRM_API_KEY`
  - [ ] `TWENTY_CRM_URL` (optionnel, pour les liens)
- [ ] Clé API créée dans Twenty CRM
- [ ] Permissions de la clé API vérifiées
- [ ] Test de l'endpoint `/api/twenty-crm/tasks` effectué
- [ ] Vérification que les tâches apparaissent dans le widget
- [ ] Logs vérifiés pour détecter d'éventuelles erreurs

---

## 📝 Notes

- Les tâches Twenty CRM sont préfixées avec `twenty-` dans leur ID pour éviter les conflits
- Le widget continue de fonctionner même si une seule source échoue (grace à `Promise.allSettled`)
- Le cache Redis n'est pas encore implémenté pour Twenty CRM (peut être ajouté plus tard)
- La requête GraphQL peut nécessiter des ajustements selon votre version de Twenty CRM