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