docs: Documentation complète de la détection automatique de fonds
- Architecture du système de détection - Flux de fonctionnement détaillé - Configuration et intégration - Dépannage et tests - Avantages et sécurité
This commit is contained in:
parent
379bd4420d
commit
3be2593ea2
243
docs/DETECTION_AUTOMATIQUE_FONDS.md
Normal file
243
docs/DETECTION_AUTOMATIQUE_FONDS.md
Normal file
@ -0,0 +1,243 @@
|
||||
# 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
|
||||
Loading…
x
Reference in New Issue
Block a user