lecoffre_node/docs/DETECTION_AUTOMATIQUE_FONDS.md

# Détection Automatique de Fonds dans les Applications

## Vue d'ensemble

Ce système implémente une détection automatique des fonds insuffisants directement dans les applications et déclenche automatiquement un transfert de fonds du wallet mining vers le relay.

## Architecture

### 1. Détection dans les Applications

#### ihm_client (Frontend)
- **Fichier**: `src/services/service.ts`
- **Méthode**: `createProcess()`
- **Détection**: Erreurs "Insufficient funds" ou "Missing sats"
- **Action**: Appel automatique à l'API de transfert

```typescript
try {
  const result = this.sdkClient.create_new_process(...);
  // ... traitement normal
} catch (error) {
  const errorMessage = error.toString().toLowerCase();
  if (errorMessage.includes('insufficient funds') || 
      (errorMessage.includes('missing') && errorMessage.includes('sats'))) {
    // Transfert automatique de fonds
    await this.triggerAutomaticFundsTransfer();
    // Retry automatique
    const retryResult = this.sdkClient.create_new_process(...);
  }
}
```

#### lecoffre-back (Backend)
- **Fichier**: `src/routes/funds.routes.ts`
- **Endpoints**:
  - `POST /api/v1/funds/transfer` - Transfert de fonds
  - `GET /api/v1/funds/check` - Vérification des fonds

### 2. Service de Détection

#### Service Node.js
- **Fichier**: `scripts/funds/funds_detector_service.js`
- **Fonctionnalités**:
  - Monitoring continu des fonds
  - Transfert automatique si nécessaire
  - Logs détaillés
  - Gestion des erreurs

### 3. Scripts de Support

#### Scripts Bash
- `scripts/funds/simple_transfer.sh` - Transfert de base
- `scripts/funds/check_and_transfer_funds.sh` - Vérification et transfert
- `scripts/funds/monitor_funds.sh` - Monitoring continu
- `scripts/startup-with-funds-check.sh` - Démarrage avec vérification

## Flux de Fonctionnement

### 1. Détection Automatique
```
Application (ihm_client) → createProcess() → Erreur "Insufficient funds"
                        ↓
                    Détection automatique
                        ↓
                    Appel API /api/v1/funds/transfer
                        ↓
                    Transfert de fonds
                        ↓
                    Retry automatique
                        ↓
                    Succès
```

### 2. API de Transfert
```http
POST /api/v1/funds/transfer
Content-Type: application/json

{
  "amount": 0.01,
  "source": "mining_mnemonic",
  "target": "default"
}
```

**Réponse:**
```json
{
  "success": true,
  "message": "Transfert de 0.01 BTC réussi",
  "transactionId": "abc123...",
  "address": "tb1q...",
  "sourceBalance": 49.99,
  "targetBalance": 0.01
}
```

### 3. Vérification des Fonds
```http
GET /api/v1/funds/check
```

**Réponse:**
```json
{
  "success": true,
  "relay": {
    "outputsCount": 1,
    "balance": 0.01
  },
  "mining": {
    "balance": 49.99
  },
  "needsTransfer": false
}
```

## Configuration

### Variables d'Environnement
- `MINING_WALLET`: "mining_mnemonic" (par défaut)
- `RELAY_WALLET`: "default" (par défaut)
- `MIN_FUNDS_THRESHOLD`: 0.001 BTC (par défaut)
- `TRANSFER_AMOUNT`: 0.01 BTC (par défaut)

### Seuils
- **Seuil minimum**: 0.001 BTC (100,000 sats)
- **Montant de transfert**: 0.01 BTC (1,000,000 sats)
- **Vérification**: Toutes les 30 secondes (service)

## Intégration

### Docker Compose
```yaml
volumes:
  - ./scripts/funds:/scripts/funds:ro
```

### Démarrage
```bash
# Démarrage avec vérification automatique
./scripts/startup-with-funds-check.sh

# Service de monitoring
node scripts/funds/funds_detector_service.js
```

## Avantages

### 1. Transparence
- L'utilisateur ne voit pas l'erreur de fonds insuffisants
- Le transfert se fait automatiquement en arrière-plan
- Retry automatique après transfert

### 2. Fiabilité
- Détection proactive des problèmes
- Transfert automatique avant échec
- Gestion des erreurs et fallback

### 3. Performance
- Pas d'interruption du workflow utilisateur
- Transfert rapide (quelques secondes)
- Monitoring continu

### 4. Maintenance
- Logs détaillés pour debugging
- Configuration flexible
- Scripts réutilisables

## Dépannage

### Problèmes Courants

1. **API non accessible**
   ```bash
   # Vérifier que lecoffre-back est démarré
   docker compose ps lecoffre-back
   
   # Vérifier les logs
   docker logs lecoffre-back
   ```

2. **Transfert échoue**
   ```bash
   # Vérifier la connectivité Bitcoin
   docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo
   
   # Vérifier les soldes
   curl http://localhost:8080/api/v1/funds/check
   ```

3. **Service de détection ne démarre pas**
   ```bash
   # Vérifier les permissions
   chmod +x scripts/funds/funds_detector_service.js
   
   # Vérifier Node.js
   node --version
   ```

### Logs
- **Service de détection**: `/tmp/funds_detector.log`
- **lecoffre-back**: `docker logs lecoffre-back`
- **ihm_client**: Console du navigateur

## Tests

### Test Manuel
```bash
# 1. Vérifier les fonds
curl http://localhost:8080/api/v1/funds/check

# 2. Transférer des fonds
curl -X POST http://localhost:8080/api/v1/funds/transfer \
  -H "Content-Type: application/json" \
  -d '{"amount": 0.01}'

# 3. Vérifier à nouveau
curl http://localhost:8080/api/v1/funds/check
```

### Test Automatique
```bash
# Lancer le service de détection
node scripts/funds/funds_detector_service.js

# Dans un autre terminal, simuler un manque de fonds
# Le service devrait détecter et transférer automatiquement
```

## Sécurité

- Vérification des soldes avant transfert
- Limitation des montants de transfert
- Logs de toutes les opérations
- Gestion des erreurs sécurisée

## Performance

- Transfert en ~5-10 secondes
- Détection en temps réel
- Monitoring toutes les 30 secondes
- Pas d'impact sur les performances utilisateur