espace-paie-odentas/DOCUSEAL_DEBUG_GUIDE.md

# Guide de Débogage - Pré-remplissage Signature DocuSeal

## Date: 14 octobre 2025

## Logs à vérifier dans la console

Lorsque vous ouvrez une signature électronique, vous devriez voir cette séquence de logs :

### 1. API Backend (`/api/contrats/[id]/signature`)

```
🔍 [API SIGNATURE] Recherche contrat ID: xxx
✅ [API SIGNATURE] Contrat trouvé: { id, org_id, ... }
🔍 [API SIGNATURE] org_id présent: xxx
🔍 [API SIGNATURE] Recherche de signature pour org_id...
📋 [API SIGNATURE] Résultat requête organization_details: {
  hasData: true/false,
  hasError: true/false,
  hasSignature: true/false,
  signatureLength: xxx,
  signaturePreview: "data:image/png;base64,..."
}
✅ [API SIGNATURE] Signature trouvée pour l'organisation
📏 [API SIGNATURE] Longueur de la signature: xxx
📤 [API SIGNATURE] Réponse finale: {
  hasSignature: true,
  signatureLength: xxx,
  contractId: xxx,
  orgId: xxx
}
```

### 2. Frontend - Récupération des données

```
🔍 [SIGNATURE] Debug - data complète: { ... }
📋 [SIGNATURE] Données contrat depuis API: { success: true, data: {...} }
🔍 [SIGNATURE] result.data: { ... }
🔍 [SIGNATURE] result.data.signature_b64: "data:image/png;base64,..."
📦 [SIGNATURE] contractData extrait: { ... }
🖊️ [SIGNATURE] signatureB64 extraite: {
  exists: true,
  type: "string",
  length: xxx,
  preview: "data:image/png;base64,..."
}
✅ [SIGNATURE] Signature B64 disponible, longueur: xxx
```

### 3. Frontend - Stockage sessionStorage

```
🔍 [SIGNATURE] Tentative de stockage de la signature...
🔍 [SIGNATURE] signatureB64 value: "data:image/png;base64,..."
📝 [SIGNATURE] Stockage de la signature dans sessionStorage
📝 [SIGNATURE] Longueur de la signature: xxx
📝 [SIGNATURE] Preview: "data:image/png;base64,..."
✅ [SIGNATURE] Signature stockée avec succès, vérification: {
  stored: true,
  length: xxx,
  matches: true
}
✅ [SIGNATURE] URL embed trouvée: https://docuseal.eu/s/xxx
```

### 4. Frontend - Rendu du composant

```
🎨 [SIGNATURE RENDER] Génération du HTML docuseal-form
🎨 [SIGNATURE RENDER] embedSrc: https://docuseal.eu/s/xxx
🎨 [SIGNATURE RENDER] Signature depuis sessionStorage: {
  exists: true,
  length: xxx,
  preview: "data:image/png;base64,..."
}
🎨 [SIGNATURE RENDER] signatureAttr généré: {
  hasAttr: true,
  attrLength: xxx,
  attrPreview: 'data-signature="data:image/png;base64,...'
}
🎨 [SIGNATURE RENDER] HTML final généré
🎨 [SIGNATURE RENDER] HTML length: xxx
🎨 [SIGNATURE RENDER] HTML contient data-signature: true
```

## Points de vérification

### Étape 1 : Vérifier la base de données

```sql
-- Vérifier que la signature existe
SELECT 
  org_id, 
  structure,
  LENGTH(signature_b64) as signature_length,
  SUBSTRING(signature_b64, 1, 50) as signature_preview
FROM organization_details
WHERE signature_b64 IS NOT NULL;
```

**Attendu** :
- Au moins une ligne avec signature_b64 non NULL
- signature_length > 0
- signature_preview commence par "data:image/"

### Étape 2 : Vérifier que le contrat a un org_id

```sql
-- Vérifier le contrat
SELECT 
  id,
  contract_number,
  org_id,
  signature_status
FROM cddu_contracts
WHERE id = 'VOTRE_CONTRACT_ID';
```

**Attendu** :
- org_id non NULL
- org_id correspond à une organisation avec signature_b64

### Étape 3 : Tester l'API directement

```bash
# Remplacer CONTRACT_ID par l'ID réel
curl http://localhost:3000/api/contrats/CONTRACT_ID/signature
```

**Attendu dans la réponse** :
```json
{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "signature_b64": "data:image/png;base64,..."
  }
}
```

### Étape 4 : Vérifier la console du navigateur

**Ouvrir DevTools (F12) → Console**

Chercher les logs :
- ✅ Tous les logs commençant par `[API SIGNATURE]`
- ✅ Tous les logs commençant par `[SIGNATURE]`
- ✅ Tous les logs commençant par `[SIGNATURE RENDER]`

### Étape 5 : Vérifier sessionStorage

**Dans DevTools → Application → Storage → Session Storage**

Chercher la clé : `docuseal_signature_b64`

**Attendu** :
- Clé présente
- Valeur commence par "data:image/"
- Valeur ressemble à du base64

### Étape 6 : Vérifier le HTML généré

**Dans DevTools → Elements**

Chercher l'élément `<docuseal-form>`

**Attendu** :
```html
<docuseal-form
  data-src="https://docuseal.eu/s/xxx"
  data-language="fr"
  data-with-title="false"
  data-background-color="#fff"
  data-allow-typed-signature="false"
  data-signature="data:image/png;base64,...">
</docuseal-form>
```

**Vérifier** :
- ✅ Attribut `data-signature` présent
- ✅ Valeur commence par "data:image/"
- ✅ Valeur contient du base64

## Problèmes courants

### Problème 1 : Pas de signature dans la base

**Symptôme** :
```
⚠️ [API SIGNATURE] Pas d'org_id sur ce contrat
```
ou
```
❌ [API SIGNATURE] Aucune signature trouvée pour cette organisation
```

**Solution** :
Ajouter la signature dans la base :
```sql
UPDATE organization_details 
SET signature_b64 = 'data:image/png;base64,VOTRE_BASE64'
WHERE org_id = 'ID_ORGANISATION';
```

### Problème 2 : Signature trop longue pour sessionStorage

**Symptôme** :
```
❌ [SIGNATURE] Erreur lors du stockage: QuotaExceededError
```

**Solution** :
- Compresser l'image de signature
- Utiliser un format plus léger (PNG optimisé)
- Limite sessionStorage : ~5-10MB selon le navigateur

### Problème 3 : Format de signature incorrect

**Symptôme** :
DocuSeal affiche une erreur ou ne pré-remplit pas

**Solution** :
Vérifier le format :
- ✅ CORRECT : `data:image/png;base64,iVBORw0KGgo...`
- ❌ INCORRECT : `iVBORw0KGgo...` (manque le préfixe)
- ❌ INCORRECT : `data:image/png,base64,iVBORw0KGgo...` (virgule au mauvais endroit)

### Problème 4 : Le composant se re-render avant le stockage

**Symptôme** :
```
🎨 [SIGNATURE RENDER] Signature depuis sessionStorage: { exists: false }
```
mais plus tôt on a vu :
```
✅ [SIGNATURE] Signature stockée avec succès
```

**Solution** :
Problème de timing React. Le sessionStorage est lu lors du premier rendu avant le stockage.

**Fix** : Forcer un re-render après le stockage :
```tsx
if (signatureB64) {
  sessionStorage.setItem('docuseal_signature_b64', signatureB64);
  // Forcer un re-render
  setEmbedSrc(null);
  setTimeout(() => setEmbedSrc(embed), 0);
}
```

## Commandes utiles

### Vérifier toutes les organisations avec signature

```sql
SELECT 
  o.id,
  o.name,
  od.structure,
  CASE 
    WHEN od.signature_b64 IS NOT NULL THEN '✅ Signature présente'
    ELSE '❌ Pas de signature'
  END as statut,
  LENGTH(od.signature_b64) as taille
FROM organizations o
LEFT JOIN organization_details od ON od.org_id = o.id
ORDER BY od.signature_b64 IS NOT NULL DESC, o.name;
```

### Vérifier les contrats prêts pour le pré-remplissage

```sql
SELECT 
  c.id,
  c.contract_number,
  c.org_id,
  o.name as organization_name,
  c.signature_status,
  CASE 
    WHEN od.signature_b64 IS NOT NULL THEN '✅ Signature dispo'
    ELSE '❌ Pas de signature'
  END as signature_employeur
FROM cddu_contracts c
LEFT JOIN organizations o ON o.id = c.org_id
LEFT JOIN organization_details od ON od.org_id = c.org_id
WHERE c.signature_status IN ('En attente', 'Signé par l''employeur')
ORDER BY c.created_at DESC
LIMIT 20;
```

## Contact

Si les logs montrent toutes les étapes OK mais que ça ne fonctionne toujours pas :
1. Copier tous les logs de la console
2. Faire une capture d'écran de l'élément `<docuseal-form>` dans DevTools
3. Vérifier la version de DocuSeal utilisée
4. Consulter la documentation DocuSeal pour `data-signature`