rpa_vision_v3/docs/GUIDE_CAPTURE_ECRAN_REELLE.md

# Guide de Capture d'Écran Réelle - RPA Vision V3

**Auteur :** Dom, Alice, Kiro - 8 janvier 2026

## Vue d'Ensemble

Le système de capture d'écran réelle de RPA Vision V3 permet de capturer en temps réel l'écran de l'utilisateur, de détecter automatiquement les éléments d'interface utilisateur, et d'interagir directement avec les applications réelles. Ce système constitue le cœur de la fonctionnalité de démonstration réelle du Visual Workflow Builder.

## Fonctionnalités Principales

### 🖥️ Capture d'Écran en Temps Réel
- Capture continue de l'écran utilisateur
- Support multi-moniteur
- Intervalles de capture configurables (0.1s à 10s)
- Conversion automatique en base64 pour l'affichage web

### 🎯 Détection d'Éléments UI
- Détection automatique des éléments d'interface
- Intégration avec le système de détection RPA Vision V3
- Classification des types d'éléments (boutons, champs, etc.)
- Calcul de confiance pour chaque élément détecté

### 🖱️ Interactions Réelles
- Clics de souris sur les éléments détectés
- Saisie de texte dans les champs réels
- Exécution de workflows sur des applications réelles
- Contrôles de sécurité et arrêt d'urgence

## Architecture du Système

```
┌─────────────────────────────────────────────────────────────┐
│                    Frontend React                           │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │  RealDemo       │  │ RealScreenCapture│                 │
│  │  Component      │  │   Component      │                 │
│  └─────────────────┘  └─────────────────┘                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP/WebSocket
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Backend Flask API                         │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              real_demo_bp (Blueprint)                   ││
│  │  /monitors, /capture/*, /interact/*, /workflow/*        ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              RealScreenCaptureService                       │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │   MSS Library   │  │   UI Detector   │                 │
│  │ (Screen Capture)│  │ (RPA Vision V3) │                 │
│  └─────────────────┘  └─────────────────┘                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Système d'Exploitation                    │
│           (Écran réel + Applications réelles)              │
└─────────────────────────────────────────────────────────────┘
```

## Installation et Configuration

### Prérequis

```bash
# Dépendances Python requises
pip install mss pillow opencv-python numpy pyautogui

# Dépendances optionnelles pour l'interaction
pip install pygetwindow  # Informations sur les fenêtres
```

### Configuration du Système

1. **Permissions d'écran** (macOS/Linux) :
   ```bash
   # Accorder les permissions de capture d'écran à votre terminal/IDE
   # Sur macOS : Préférences Système > Sécurité > Confidentialité > Enregistrement d'écran
   ```

2. **Variables d'environnement** :
   ```bash
   # Activer les tests d'interaction réelle (optionnel)
   export ENABLE_REAL_INTERACTION_TESTS=1
   
   # Configuration de sécurité PyAutoGUI
   export PYAUTOGUI_FAILSAFE=1
   ```

## Utilisation

### 1. Interface Web (Recommandé)

#### Démarrage du Serveur
```bash
# Démarrer le serveur backend
cd visual_workflow_builder/backend
python app.py

# Démarrer le frontend React
cd ../frontend
npm start
```

#### Utilisation de l'Interface
1. Ouvrir le Visual Workflow Builder dans le navigateur
2. Aller dans l'onglet "Démonstration Réelle"
3. Sélectionner l'onglet "Capture d'Écran Réelle"
4. Choisir le moniteur à capturer
5. Configurer l'intervalle de capture
6. Cliquer sur "Démarrer" pour commencer la capture

### 2. API REST Directe

#### Endpoints Disponibles

**Gestion des Moniteurs :**
```bash
# Lister les moniteurs
GET /api/real-demo/monitors

# Sélectionner un moniteur
POST /api/real-demo/monitors/{id}/select
```

**Contrôle de la Capture :**
```bash
# Démarrer la capture
POST /api/real-demo/capture/start
Content-Type: application/json
{
  "interval": 1.0
}

# Arrêter la capture
POST /api/real-demo/capture/stop

# Obtenir le statut
GET /api/real-demo/capture/status

# Récupérer le screenshot actuel
GET /api/real-demo/capture/screenshot
```

**Interactions :**
```bash
# Effectuer un clic
POST /api/real-demo/interact/click
Content-Type: application/json
{
  "x": 100,
  "y": 200
}
# OU
{
  "element_id": "detected_element_123"
}

# Saisir du texte
POST /api/real-demo/interact/type
Content-Type: application/json
{
  "text": "Bonjour RPA Vision V3",
  "x": 100,
  "y": 200
}
```

**Exécution de Workflows :**
```bash
# Exécuter un workflow simple
POST /api/real-demo/workflow/execute
Content-Type: application/json
{
  "actions": [
    {"type": "click", "x": 100, "y": 200},
    {"type": "wait", "duration": 1.0},
    {"type": "type", "text": "Hello World"}
  ]
}
```

### 3. Utilisation Programmatique

```python
from visual_workflow_builder.backend.services.real_screen_capture import RealScreenCaptureService

# Initialiser le service
service = RealScreenCaptureService()

try:
    # Obtenir les moniteurs
    monitors = service.get_monitors()
    print(f"Moniteurs disponibles: {len(monitors)}")
    
    # Sélectionner le premier moniteur
    service.select_monitor(0)
    
    # Démarrer la capture
    service.start_capture(interval=1.0)
    
    # Attendre et obtenir des données
    time.sleep(3)
    screenshot = service.get_current_screenshot_base64()
    elements = service.get_detected_elements()
    
    print(f"Éléments détectés: {len(elements)}")
    
    # Arrêter la capture
    service.stop_capture()
    
finally:
    service.cleanup()
```

## Exemples d'Utilisation

### Exemple 1 : Capture Simple

```python
import time
from visual_workflow_builder.backend.services.real_screen_capture import RealScreenCaptureService

def capture_simple():
    service = RealScreenCaptureService()
    
    # Démarrer la capture
    service.start_capture(interval=2.0)
    
    # Capturer pendant 10 secondes
    for i in range(5):
        time.sleep(2)
        elements = service.get_detected_elements()
        print(f"Capture {i+1}: {len(elements)} éléments détectés")
    
    # Arrêter
    service.stop_capture()
    service.cleanup()

capture_simple()
```

### Exemple 2 : Interaction Automatisée

```python
import requests
import time

def interaction_automatisee():
    base_url = "http://localhost:5002/api/real-demo"
    
    # Démarrer la capture
    requests.post(f"{base_url}/capture/start", json={"interval": 1.0})
    
    # Attendre la détection
    time.sleep(3)
    
    # Obtenir les éléments
    response = requests.get(f"{base_url}/elements")
    elements = response.json()["elements"]
    
    # Cliquer sur le premier bouton trouvé
    for element in elements:
        if element["type"] == "button":
            requests.post(f"{base_url}/interact/click", 
                         json={"element_id": element["id"]})
            break
    
    # Arrêter la capture
    requests.post(f"{base_url}/capture/stop")

interaction_automatisee()
```

### Exemple 3 : Workflow Complexe

```python
def workflow_complexe():
    workflow = {
        "actions": [
            # Cliquer sur un champ de recherche
            {"type": "click", "x": 300, "y": 100},
            {"type": "wait", "duration": 0.5},
            
            # Saisir une recherche
            {"type": "type", "text": "RPA Vision V3"},
            {"type": "wait", "duration": 0.5},
            
            # Appuyer sur Entrée (simulé par un clic sur un bouton)
            {"type": "click", "x": 400, "y": 100},
            {"type": "wait", "duration": 2.0},
            
            # Cliquer sur le premier résultat
            {"type": "click", "x": 300, "y": 200}
        ]
    }
    
    response = requests.post(
        "http://localhost:5002/api/real-demo/workflow/execute",
        json=workflow
    )
    
    result = response.json()
    print(f"Workflow terminé: {result['summary']['success_rate']:.1%} de réussite")

workflow_complexe()
```

## Tests et Validation

### Tests Automatisés

```bash
# Exécuter les tests unitaires
python -m pytest tests/test_real_screen_capture_system.py -v

# Tests avec interactions réelles (nécessite ENABLE_REAL_INTERACTION_TESTS=1)
ENABLE_REAL_INTERACTION_TESTS=1 python -m pytest tests/test_real_screen_capture_system.py::TestRealInteractionSystem -v
```

### Démonstration Complète

```bash
# Exécuter la démonstration complète
python demo_real_screen_capture_complete.py
```

### Test Manuel

```bash
# Test manuel du service
python tests/test_real_screen_capture_system.py
```

## Sécurité et Bonnes Pratiques

### Contrôles de Sécurité

1. **Arrêt d'Urgence** :
   - Endpoint `/safety/emergency-stop` pour arrêter toutes les interactions
   - PyAutoGUI failsafe : déplacer la souris dans le coin supérieur gauche

2. **Validation des Entrées** :
   - Validation des coordonnées de clic
   - Limitation de la longueur du texte à saisir
   - Validation des intervalles de capture

3. **Permissions** :
   - Vérifier les permissions de capture d'écran
   - Demander confirmation pour les interactions

### Bonnes Pratiques

1. **Performance** :
   ```python
   # Utiliser des intervalles appropriés
   service.start_capture(interval=1.0)  # Bon pour la démo
   service.start_capture(interval=0.1)  # Trop fréquent, éviter
   ```

2. **Gestion des Erreurs** :
   ```python
   try:
       service.start_capture()
       # ... utilisation ...
   except Exception as e:
       print(f"Erreur: {e}")
   finally:
       service.cleanup()  # Toujours nettoyer
   ```

3. **Ressources** :
   ```python
   # Arrêter la capture quand elle n'est plus nécessaire
   if not needed:
       service.stop_capture()
   ```

## Dépannage

### Problèmes Courants

1. **Capture d'écran noire** :
   - Vérifier les permissions de capture d'écran
   - Tester avec un autre moniteur
   - Redémarrer l'application

2. **Aucun élément détecté** :
   - Vérifier que des éléments UI sont visibles à l'écran
   - Augmenter l'intervalle de capture
   - Vérifier les logs du détecteur UI

3. **Interactions ne fonctionnent pas** :
   - Vérifier que PyAutoGUI est installé
   - Désactiver le failsafe temporairement pour les tests
   - Vérifier les coordonnées de clic

4. **API non accessible** :
   - Vérifier que le serveur backend est démarré
   - Contrôler le port (5002 par défaut)
   - Vérifier les logs du serveur

### Logs et Débogage

```python
import logging

# Activer les logs détaillés
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# Le service utilise le logger pour tracer les opérations
service = RealScreenCaptureService()
```

### Variables d'Environnement de Débogage

```bash
# Logs détaillés
export PYTHONPATH=/path/to/rpa_vision_v3
export LOG_LEVEL=DEBUG

# Tests d'interaction
export ENABLE_REAL_INTERACTION_TESTS=1

# Configuration PyAutoGUI
export PYAUTOGUI_FAILSAFE=0  # Désactiver le failsafe (attention !)
```

## Intégration avec RPA Vision V3

Le système de capture d'écran réelle s'intègre parfaitement avec les autres composants de RPA Vision V3 :

- **UIDetector** : Utilise le détecteur UI existant pour analyser les captures
- **ScreenCapturer** : Compatible avec le système de capture existant
- **ActionExecutor** : Peut exécuter des actions sur les éléments détectés
- **WorkflowGraph** : Intégration future pour l'exécution de workflows complets

## Roadmap et Améliorations Futures

### Fonctionnalités Prévues

1. **Apprentissage Adaptatif** :
   - Mémorisation des éléments fréquemment utilisés
   - Adaptation aux changements d'interface

2. **Workflows Avancés** :
   - Conditions et boucles dans les workflows
   - Gestion des erreurs et retry automatique

3. **Performance** :
   - Optimisation de la détection d'éléments
   - Cache intelligent des captures

4. **Sécurité Renforcée** :
   - Authentification pour les interactions
   - Audit trail des actions effectuées

### Contributions

Pour contribuer au développement :

1. Suivre les conventions de code du projet
2. Ajouter des tests pour les nouvelles fonctionnalités
3. Documenter les changements en français
4. Respecter l'architecture existante

---

**Note :** Ce système permet des interactions réelles avec votre ordinateur. Utilisez-le avec précaution et assurez-vous de comprendre les implications de sécurité avant de l'utiliser en production.