# Documentation ActionExecutor

**Auteur**: Dom, Alice Kiro - 15 décembre 2024

## Vue d'ensemble

L'ActionExecutor est le composant central responsable de l'exécution automatique des actions de workflow dans RPA Vision V3. Il fait partie de la couche d'exécution (`core/execution/`) et implémente un système robuste d'exécution d'actions avec gestion d'erreurs et stratégies de récupération.

## Architecture

### Classes principales

#### ExecutionStatus (Enum)
Énumération des statuts d'exécution possibles :
- `SUCCESS`: Exécution réussie
- `FAILED`: Échec d'exécution
- `TIMEOUT`: Timeout dépassé
- `PRECONDITION_FAILED`: Pré-conditions non satisfaites
- `POSTCONDITION_FAILED`: Post-conditions non satisfaites
- `TARGET_NOT_FOUND`: Cible non trouvée

#### ExecutionResult (Dataclass)
Résultat d'une exécution d'action contenant :
- `status`: Statut d'exécution
- `message`: Message descriptif
- `duration_ms`: Durée d'exécution en millisecondes
- `target_resolved`: Cible résolue (optionnel)
- `error`: Exception capturée (optionnel)

#### ActionExecutor
Classe principale gérant l'exécution des actions avec :
- Résolution de cibles via TargetResolver
- Gestion d'erreurs via ErrorHandler
- Vérification des pré/post-conditions
- Stratégies de fallback multiples

## Types d'actions supportés

### 1. MOUSE_CLICK
Exécution de clics souris avec :
- Résolution automatique de la cible
- Calcul de position de clic (centre de l'élément)
- Support des offsets personnalisés
- Stratégies de fallback multiples

### 2. TEXT_INPUT
Saisie de texte avec :
- Clic automatique pour focus
- Substitution de variables depuis le contexte
- Gestion des délais d'attente

### 3. COMPOUND
Exécution de séquences d'actions avec :
- Politiques de répétition configurables
- Gestion des échecs en cascade

## Stratégies de fallback

### Fallback par similarité visuelle
- Utilise les embeddings visuels CLIP
- Seuil de similarité : 0.75
- Recherche l'élément le plus similaire visuellement

### Fallback par position approximative
- Utilise les positions historiques
- Seuil de distance : 100 pixels
- Trouve l'élément le plus proche géographiquement

## Gestion des erreurs

### Types d'erreurs gérés
- Cible non trouvée (TARGET_NOT_FOUND)
- Violation de post-conditions (POSTCONDITION_VIOLATION)
- Timeouts d'exécution

### Stratégies de récupération
- RETRY : Nouvelle tentative avec fallbacks
- ROLLBACK : Annulation de la dernière action
- SKIP : Ignorer l'action et continuer

## Configuration

### Paramètres par défaut
- `default_timeout_ms`: 5000ms
- `verify_postconditions`: True
- `pyautogui.PAUSE`: 0.1s entre actions
- `pyautogui.FAILSAFE`: True (sécurité)

### Délais d'attente
- Après clic : 500ms (configurable)
- Après saisie : 500ms (configurable)
- Vérification post-conditions : 5000ms

## Intégration avec les autres composants

### TargetResolver
- Résolution de cibles par rôle sémantique
- Recherche dans les éléments UI détectés
- Support des critères de matching avancés

### ErrorHandler
- Enregistrement des actions pour rollback
- Logging structuré des erreurs
- Statistiques d'échecs par edge

### ScreenState
- Accès aux éléments UI détectés
- Contexte de fenêtre active
- Embeddings pour fallbacks

## Métriques et monitoring

### Statistiques collectées
- Durée d'exécution par action
- Taux de succès par type d'action
- Utilisation des stratégies de fallback
- Fréquence des violations de post-conditions

### Logging
- Niveau DEBUG : Détails d'exécution
- Niveau INFO : Actions principales
- Niveau WARNING : Fallbacks utilisés
- Niveau ERROR : Échecs critiques

## Exemples d'utilisation

### Exécution simple
```python
executor = ActionExecutor()
result = executor.execute_edge(edge, screen_state)
if result.status == ExecutionStatus.SUCCESS:
    print(f"Action réussie en {result.duration_ms}ms")
```

### Avec contexte de variables
```python
context = {"username": "alice", "password": "secret"}
result = executor.execute_edge(edge, screen_state, context)
```

### Configuration personnalisée
```python
executor = ActionExecutor(
    default_timeout_ms=10000,
    verify_postconditions=False
)
```

## Évolutions futures

### Améliorations prévues
- Support des actions de glisser-déposer
- Reconnaissance de gestes complexes
- Adaptation dynamique des seuils de fallback
- Apprentissage des patterns d'échec

### Optimisations
- Cache des résolutions de cibles
- Prédiction des positions futures
- Parallélisation des vérifications
- Réduction des délais d'attente

## Tests et validation

### Tests unitaires
- Couverture de tous les types d'actions
- Simulation des échecs de résolution
- Validation des stratégies de fallback

### Tests d'intégration
- Workflows complets end-to-end
- Interaction avec composants réels
- Performance sous charge

### Tests de robustesse
- Gestion des changements d'UI
- Récupération après pannes
- Comportement en mode dégradé

---

*Cette documentation fait partie du système RPA Vision V3 - Architecture 5 couches*