rpa_vision_v3/.kiro/specs/agent-workflow-improvements/design.md

# Document de Conception - Améliorations Agent V0

## Vue d'Ensemble de l'Architecture

Cette conception détaille les améliorations à apporter à l'Agent V0 pour résoudre les 5 problèmes identifiés : nommage des workflows, capture d'événements incomplète, captures d'écran limitées, visibilité du traitement, et découvrabilité des workflows.

## Architecture Actuelle vs Proposée

### Architecture Actuelle
```
Agent V0
├── Capture basique (clics, scroll, hover)
├── Screenshots plein écran uniquement
├── Nommage générique des sessions
├── Upload simple vers serveur
└── Aucun feedback de traitement
```

### Architecture Proposée
```
Agent V0 Amélioré
├── Capture enrichie (clavier + contexte)
├── Screenshots intelligents (ciblés + plein écran)
├── Nommage intelligent basé sur l'analyse UI
├── Monitoring pipeline en temps réel
├── Interface de découverte des workflows
└── Intégration Visual Workflow Builder
```

## Composants de Conception

### 1. Système de Nommage Intelligent

#### 1.1 Analyseur d'Actions
```python
class ActionAnalyzer:
    """Analyse les actions capturées pour générer des noms descriptifs"""
    
    def analyze_session(self, raw_session: RawSession) -> SessionAnalysis:
        """Analyse une session pour extraire les patterns d'actions"""
        
    def extract_ui_elements(self, events: List[Event]) -> List[UIElement]:
        """Extrait les éléments UI interagis"""
        
    def detect_workflow_type(self, analysis: SessionAnalysis) -> WorkflowType:
        """Détecte le type de workflow (formulaire, navigation, etc.)"""
```

#### 1.2 Générateur de Noms
```python
class WorkflowNameGenerator:
    """Génère des noms descriptifs pour les workflows"""
    
    def generate_name(self, analysis: SessionAnalysis) -> str:
        """Génère un nom basé sur l'analyse de session"""
        
    def suggest_alternatives(self, base_name: str) -> List[str]:
        """Propose des noms alternatifs"""
        
    def ensure_uniqueness(self, name: str, existing_names: List[str]) -> str:
        """Assure l'unicité du nom généré"""
```

#### 1.3 Patterns de Nommage
- **Formulaires**: "Saisie_[NomFormulaire]_[Date]"
- **Navigation**: "Navigation_[Application]_vers_[Section]"
- **Recherche**: "Recherche_[Terme]_dans_[Application]"
- **Édition**: "Modification_[TypeDocument]_[Action]"
- **Générique**: "Workflow_[Application]_[Timestamp]"

### 2. Capture d'Événements Étendue

#### 2.1 Capteur de Clavier Enrichi
```python
class EnhancedKeyCaptor:
    """Capture enrichie des événements clavier"""
    
    def capture_text_input(self, text: str, target_element: UIElement):
        """Capture la saisie de texte avec son contexte"""
        
    def capture_keyboard_shortcut(self, keys: List[str], context: AppContext):
        """Capture les raccourcis clavier avec leur signification"""
        
    def capture_special_keys(self, key: str, target_element: UIElement):
        """Capture les touches spéciales (Tab, Enter, etc.)"""
```

#### 2.2 Détecteur de Contexte UI
```python
class UIContextDetector:
    """Détecte le contexte des éléments UI lors des interactions"""
    
    def get_element_context(self, position: Tuple[int, int]) -> UIElement:
        """Identifie l'élément UI à une position donnée"""
        
    def detect_element_type(self, element: UIElement) -> ElementType:
        """Détermine le type d'élément (input, button, etc.)"""
        
    def extract_element_properties(self, element: UIElement) -> Dict:
        """Extrait les propriétés de l'élément (texte, attributs, etc.)"""
```

### 3. Système de Captures Intelligentes

#### 3.1 Gestionnaire de Captures Ciblées
```python
class SmartScreenCapturer:
    """Système de capture d'écran intelligent"""
    
    def capture_targeted_area(self, center: Tuple[int, int], context_size: int):
        """Capture une zone ciblée autour d'un point"""
        
    def capture_element_context(self, element: UIElement):
        """Capture le contexte visuel d'un élément UI"""
        
    def optimize_capture_quality(self, image: Image, importance: float):
        """Optimise la qualité selon l'importance de la capture"""
```

#### 3.2 Stratégies de Capture
- **Capture Ciblée**: Zone de 400x400px autour de l'interaction
- **Capture Contextuelle**: Zone étendue incluant les éléments voisins
- **Capture Plein Écran**: Maintenue pour le contexte global
- **Capture Adaptative**: Taille ajustée selon le type d'élément

### 4. Monitoring du Pipeline de Traitement

#### 4.1 Client de Monitoring
```python
class PipelineMonitor:
    """Monitore le traitement des sessions sur le serveur"""
    
    def track_session_processing(self, session_id: str) -> ProcessingStatus:
        """Suit le traitement d'une session"""
        
    def get_processing_progress(self, session_id: str) -> ProgressInfo:
        """Obtient le progrès de traitement"""
        
    def subscribe_to_updates(self, session_id: str, callback: Callable):
        """S'abonne aux mises à jour de traitement"""
```

#### 4.2 Interface de Statut
```python
class StatusDisplay:
    """Affiche le statut de traitement dans l'interface"""
    
    def show_processing_status(self, status: ProcessingStatus):
        """Affiche le statut actuel"""
        
    def update_progress_bar(self, progress: float):
        """Met à jour la barre de progression"""
        
    def show_completion_notification(self, workflow_info: WorkflowInfo):
        """Notifie la completion du traitement"""
```

### 5. Interface de Découverte des Workflows

#### 5.1 Navigateur de Workflows
```python
class WorkflowBrowser:
    """Interface de navigation et recherche des workflows"""
    
    def list_workflows(self, filters: WorkflowFilters) -> List[WorkflowInfo]:
        """Liste les workflows avec filtres"""
        
    def search_workflows(self, query: str) -> List[WorkflowInfo]:
        """Recherche dans les workflows"""
        
    def get_workflow_preview(self, workflow_id: str) -> WorkflowPreview:
        """Obtient un aperçu du workflow"""
```

#### 5.2 Système de Filtres
- **Par Date**: Aujourd'hui, Cette semaine, Ce mois, Personnalisé
- **Par Type**: Formulaire, Navigation, Recherche, Édition, Autre
- **Par Application**: Groupement par application cible
- **Par Statut**: Brouillon, Prêt, En cours d'utilisation, Archivé

### 6. Intégration Visual Workflow Builder

#### 6.1 Connecteur VWB
```python
class VWBConnector:
    """Connecteur vers le Visual Workflow Builder"""
    
    def open_workflow_in_builder(self, workflow_id: str):
        """Ouvre un workflow dans le builder"""
        
    def sync_workflow_changes(self, workflow_id: str, changes: Dict):
        """Synchronise les modifications"""
        
    def test_workflow_from_agent(self, workflow_id: str) -> TestResult:
        """Lance un test du workflow depuis l'agent"""
```

## Flux de Données

### 1. Flux de Capture Amélioré
```
Interaction Utilisateur
    ↓
Capture Enrichie (position + contexte + métadonnées)
    ↓
Analyse UI en Temps Réel
    ↓
Capture Ciblée + Plein Écran
    ↓
Enrichissement Métadonnées
    ↓
Génération Nom Intelligent
    ↓
Packaging Session + Upload
```

### 2. Flux de Monitoring
```
Upload Session
    ↓
Serveur Démarre Traitement
    ↓
Agent Surveille Progression
    ↓
Mises à Jour Temps Réel
    ↓
Notification Completion
    ↓
Workflow Disponible
```

## Interfaces Utilisateur

### 1. Interface Principale Améliorée
```
┌─────────────────────────────────────────┐
│ Agent V0 - Capture Intelligente        │
├─────────────────────────────────────────┤
│ ● Enregistrement: [ACTIF]              │
│ 📝 Nom: "Saisie_Commande_Client"       │
│ 🎯 Actions: 12 | ⌨️ Saisies: 5         │
│ 📸 Captures: 8 (6 ciblées, 2 globales) │
├─────────────────────────────────────────┤
│ [Arrêter] [Pause] [Paramètres]         │
│ [Mes Workflows] [Aide]                  │
└─────────────────────────────────────────┘
```

### 2. Interface de Découverte
```
┌─────────────────────────────────────────┐
│ Mes Workflows                           │
├─────────────────────────────────────────┤
│ 🔍 [Rechercher...]  📅 [Filtres]       │
├─────────────────────────────────────────┤
│ 📋 Saisie_Commande_Client               │
│    Créé: 22/12/2025 | Utilisé: 3 fois  │
│    [Ouvrir] [Éditer] [Dupliquer]       │
├─────────────────────────────────────────┤
│ 🌐 Navigation_CRM_Contacts              │
│    Créé: 21/12/2025 | Utilisé: 1 fois  │
│    [Ouvrir] [Éditer] [Dupliquer]       │
└─────────────────────────────────────────┘
```

### 3. Monitoring de Traitement
```
┌─────────────────────────────────────────┐
│ Traitement en Cours                     │
├─────────────────────────────────────────┤
│ Session: Saisie_Commande_Client         │
│ ████████████░░░░ 75%                    │
│                                         │
│ ✅ Analyse des captures                 │
│ ✅ Détection des éléments UI            │
│ 🔄 Génération du workflow               │
│ ⏳ Optimisation des actions             │
│                                         │
│ Temps estimé: 30 secondes               │
└─────────────────────────────────────────┘
```

## Modèles de Données

### 1. Session Enrichie
```python
@dataclass
class EnhancedRawSession(RawSession):
    """Session avec métadonnées enrichies"""
    workflow_name: str
    workflow_type: WorkflowType
    ui_elements_detected: List[UIElement]
    text_inputs: List[TextInput]
    keyboard_shortcuts: List[KeyboardShortcut]
    targeted_captures: List[TargetedCapture]
    quality_score: float
    processing_hints: Dict[str, Any]
```

### 2. Élément UI Enrichi
```python
@dataclass
class EnhancedUIElement:
    """Élément UI avec contexte enrichi"""
    position: Tuple[int, int]
    size: Tuple[int, int]
    element_type: ElementType
    text_content: Optional[str]
    attributes: Dict[str, str]
    parent_context: Optional['EnhancedUIElement']
    interaction_type: InteractionType
    confidence_score: float
```

### 3. Capture Ciblée
```python
@dataclass
class TargetedCapture:
    """Capture d'écran ciblée avec métadonnées"""
    capture_id: str
    center_position: Tuple[int, int]
    capture_size: Tuple[int, int]
    target_element: EnhancedUIElement
    context_elements: List[EnhancedUIElement]
    capture_reason: CaptureReason
    quality_level: QualityLevel
    file_path: str
```

## Stratégies d'Implémentation

### Phase 1: Nommage Intelligent
1. Implémenter l'analyseur d'actions
2. Créer le générateur de noms
3. Intégrer dans l'interface de capture
4. Tests avec différents types de workflows

### Phase 2: Capture Enrichie
1. Étendre le capteur de clavier
2. Implémenter la détection de contexte UI
3. Intégrer les captures ciblées
4. Optimiser les performances

### Phase 3: Monitoring et Découverte
1. Créer le client de monitoring
2. Implémenter l'interface de statut
3. Développer le navigateur de workflows
4. Intégrer les filtres et recherche

### Phase 4: Intégration VWB
1. Développer le connecteur VWB
2. Implémenter la synchronisation
3. Créer l'interface d'édition
4. Tests d'intégration complets

## Considérations Techniques

### Performance
- Captures ciblées en arrière-plan pour éviter les ralentissements
- Cache des analyses UI pour éviter les recalculs
- Compression intelligente des captures selon leur importance

### Sécurité
- Chiffrement maintenu pour toutes les nouvelles données
- Anonymisation optionnelle des captures sensibles
- Validation des métadonnées avant stockage

### Compatibilité
- Support des 3 plateformes (Linux, macOS, Windows)
- Rétrocompatibilité avec les sessions existantes
- Migration progressive des fonctionnalités

## Métriques de Succès

### Métriques Quantitatives
- Temps de génération de nom < 2 secondes
- Taux de captures ciblées réussies > 95%
- Temps de découverte de workflow < 10 secondes
- Réduction de 50% des sessions incomplètes

### Métriques Qualitatives
- Satisfaction utilisateur > 4.5/5
- Adoption des nouvelles fonctionnalités > 80%
- Réduction des demandes de support
- Amélioration de la qualité des workflows générés