rpa_vision_v3/docs/reference/ACTION_EXECUTOR_DOCUMENTATION.md

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

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

context = {"username": "alice", "password": "secret"}
result = executor.execute_edge(edge, screen_state, context)

Configuration personnalisée

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