ihm_client/docs/LOGGING_GUIDELINES.md

# Guide des bonnes pratiques de logging

## Vue d'ensemble

Ce document décrit les bonnes pratiques pour l'utilisation des logs dans l'application 4NK. Nous utilisons un système de logging centralisé avec `secureLogger` pour assurer la cohérence et la sécurité.

## Système de logging

### SecureLogger

Le `secureLogger` est le système de logging principal de l'application. Il fournit :

- **Sanitisation automatique** des données sensibles
- **Niveaux de log structurés** (DEBUG, INFO, WARN, ERROR)
- **Contexte enrichi** avec composant et métadonnées
- **Formatage cohérent** des messages

### Import

```typescript
import { secureLogger } from '../services/secure-logger';
```

## Niveaux de log

### DEBUG
Utilisé pour les informations de débogage détaillées, généralement utiles uniquement lors du développement.

```typescript
secureLogger.debug('Memory usage after cleanup: 45.2%', { component: 'Service' });
secureLogger.debug('Checking credentials availability', { component: 'HomePage' });
```

**Quand utiliser :**
- Informations de débogage
- État interne des variables
- Progression des opérations complexes
- Messages avec emoji 🔍

### INFO
Utilisé pour les informations générales sur le fonctionnement de l'application.

```typescript
secureLogger.info('Home/Pairing page loaded', { component: 'HomePage' });
secureLogger.info('Services initialized successfully', { component: 'Service' });
```

**Quand utiliser :**
- Initialisation de composants
- Succès d'opérations
- Messages avec emoji ✅, 🔄, 🚀
- Événements importants du flux utilisateur

### WARN
Utilisé pour les avertissements qui n'empêchent pas le fonctionnement mais méritent attention.

```typescript
secureLogger.warn('High memory detected, performing cleanup', { component: 'Service' });
secureLogger.warn('Home page already initializing, skipping...', { component: 'HomePage' });
```

**Quand utiliser :**
- Conditions non critiques mais inhabituelles
- Messages avec emoji ⚠️
- Opérations de récupération
- Dégradations de performance

### ERROR
Utilisé pour les erreurs qui empêchent le fonctionnement normal.

```typescript
secureLogger.error('Failed to initialize services', error, { component: 'Service' });
secureLogger.error('Authentication failed', error, { component: 'HomePage' });
```

**Quand utiliser :**
- Erreurs critiques
- Messages avec emoji ❌
- Échecs d'opérations importantes
- Exceptions non gérées

## Contexte et métadonnées

### Composant

Toujours spécifier le composant dans le contexte :

```typescript
secureLogger.info('Operation completed', { component: 'HomePage' });
secureLogger.error('Database connection failed', error, { component: 'Service' });
```

### Métadonnées supplémentaires

Ajouter des métadonnées utiles pour le débogage :

```typescript
secureLogger.debug('Wallet details', {
  component: 'HomePage',
  hasSpendKey: !!wallet.sp_wallet?.spend_key,
  hasScanKey: !!wallet.sp_wallet?.scan_key,
  birthday: wallet.sp_wallet?.birthday
});
```

## Bonnes pratiques

### 1. Utiliser secureLogger au lieu de console.*

❌ **Mauvais :**
```typescript
console.log('User authenticated');
console.error('Database error:', error);
```

✅ **Bon :**
```typescript
secureLogger.info('User authenticated', { component: 'AuthService' });
secureLogger.error('Database error', error, { component: 'DatabaseService' });
```

### 2. Messages clairs et concis

❌ **Mauvais :**
```typescript
secureLogger.info('x', { component: 'Service' });
secureLogger.info('Processing user request with id 12345 and data {name: "John", email: "john@example.com"}', { component: 'UserService' });
```

✅ **Bon :**
```typescript
secureLogger.info('Processing user request', {
  component: 'UserService',
  userId: 12345,
  userName: 'John'
});
```

### 3. Niveaux appropriés

❌ **Mauvais :**
```typescript
secureLogger.error('User clicked button'); // Pas une erreur
secureLogger.info('Critical system failure'); // Pas une info
```

✅ **Bon :**
```typescript
secureLogger.debug('User clicked button', { component: 'UI' });
secureLogger.error('Critical system failure', error, { component: 'System' });
```

### 4. Contexte enrichi

❌ **Mauvais :**
```typescript
secureLogger.info('Operation failed');
```

✅ **Bon :**
```typescript
secureLogger.error('Operation failed', error, {
  component: 'PaymentService',
  operation: 'processPayment',
  userId: user.id,
  amount: payment.amount
});
```

### 5. Gestion des erreurs

```typescript
try {
  await riskyOperation();
  secureLogger.info('Operation completed successfully', { component: 'Service' });
} catch (error) {
  secureLogger.error('Operation failed', error, {
    component: 'Service',
    operation: 'riskyOperation'
  });
  throw error;
}
```

## Patterns d'emojis

### DEBUG (🔍)
- `🔍 Checking...`
- `🔍 Debug info:`
- `🔍 Memory usage:`

### INFO (✅, 🔄, 🚀)
- `✅ Operation completed`
- `🔄 Processing...`
- `🚀 Starting...`
- `🔧 Initializing...`

### WARN (⚠️)
- `⚠️ Warning:`
- `⚠️ Skipping...`
- `⚠️ High memory detected`

### ERROR (❌)
- `❌ Error:`
- `❌ Failed to:`
- `❌ Critical error:`

## Exemples par composant

### Service
```typescript
secureLogger.info('Service initialized', { component: 'Service' });
secureLogger.debug('Memory usage: 45.2%', { component: 'Service' });
secureLogger.warn('High memory detected', { component: 'Service' });
secureLogger.error('Service initialization failed', error, { component: 'Service' });
```

### HomePage
```typescript
secureLogger.info('Home page loaded', { component: 'HomePage' });
secureLogger.info('Prerequisites verified', { component: 'HomePage' });
secureLogger.warn('Already initializing, skipping', { component: 'HomePage' });
secureLogger.error('Page initialization failed', error, { component: 'HomePage' });
```

### PairingPage
```typescript
secureLogger.info('Pairing page loaded', { component: 'PairingPage' });
secureLogger.info('Pairing process started', { component: 'PairingPage' });
secureLogger.warn('Pairing already in progress', { component: 'PairingPage' });
secureLogger.error('Pairing failed', error, { component: 'PairingPage' });
```

## Outils de correction

Un script automatique est disponible pour corriger les logs existants :

```bash
node fix-logs.cjs
```

Ce script :
- Remplace `console.*` par `secureLogger.*`
- Ajoute les imports nécessaires
- Détermine automatiquement les niveaux appropriés
- Ajoute le contexte de composant

## Vérification

Pour vérifier que tous les logs utilisent le système centralisé :

```bash
grep -r "console\.\(log\|info\|warn\|error\|debug\)" src/
```

Cette commande ne devrait retourner aucun résultat si tous les logs sont correctement migrés.