253 lines
6.8 KiB
Markdown
253 lines
6.8 KiB
Markdown
# 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
|